https://github.com/unohee/openswarm
OpenSwarm β Autonomous AI dev team orchestrator powered by Claude Code CLI. Discord control, Linear integration, cognitive memory.
https://github.com/unohee/openswarm
ai-agents ai-coding autonomous-agents claude claude-code devops discord-bot linear llm multi-agent orchestrator pair-programming typescript vector-database
Last synced: about 17 hours ago
JSON representation
OpenSwarm β Autonomous AI dev team orchestrator powered by Claude Code CLI. Discord control, Linear integration, cognitive memory.
- Host: GitHub
- URL: https://github.com/unohee/openswarm
- Owner: unohee
- License: mit
- Created: 2026-02-23T07:14:58.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T12:57:26.000Z (2 days ago)
- Last Synced: 2026-07-03T13:14:50.143Z (2 days ago)
- Topics: ai-agents, ai-coding, autonomous-agents, claude, claude-code, devops, discord-bot, linear, llm, multi-agent, orchestrator, pair-programming, typescript, vector-database
- Language: TypeScript
- Homepage:
- Size: 2.82 MB
- Stars: 813
- Watchers: 5
- Forks: 142
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# OpenSwarm
[](https://www.npmjs.com/package/@intrect/openswarm)
[](https://www.npmjs.com/package/@intrect/openswarm)
[](LICENSE)
[](benchmarks/RUBRIC.md)
[](https://github.com/unohee/OpenSwarm/discussions)
> Autonomous AI agent orchestrator β Codex, GPT, **OpenRouter (any model)**, local models (Ollama/LM Studio), and Claude Code (`claude -p`)
> π¬ **Help shape OpenSwarm.** Share feature ideas, vote on the roadmap, and ask questions in [**GitHub Discussions**](https://github.com/unohee/OpenSwarm/discussions). The roadmap is built in the open β your feedback decides what ships next.
---
OpenSwarm orchestrates multiple AI agents as autonomous code workers. It picks up issues from **Linear or a built-in local tracker**, runs Worker/Reviewer pair pipelines, reports through a pluggable notifier (Discord, Slack, Telegram, webhook), and retains long-term memory via LanceDB. Workers run on **OpenAI Codex/GPT**, **any OpenRouter model**, **local open-source models** (Ollama, LM Studio), or **Claude Code** (`claude -p`, opt-in) β with cost-aware routing measured on an L0βL6 benchmark ladder.
**Verified on real GitHub issues**: the agentic harness solves SWE-bench Lite instances graded by the official harness. Hybrid mode β a frontier model diagnoses read-only, a lightweight model implements with a verification loop β resolved **3/3 attempted instances** that every single lightweight model had failed, at a fraction of frontier-only cost. Workers also **learn each repository over time**: task outcomes are stored as per-repo knowledge and recalled into future prompts. ([benchmark rubric & results](benchmarks/RUBRIC.md))
## Quick Start
```bash
npm install -g @intrect/openswarm
openswarm init # interactive setup wizard β provider auth + Linear OAuth + config
openswarm doctor # verify your environment (runtime, native deps, providers, ports)
openswarm # launches the TUI chat
```
`openswarm init` walks you through provider authentication, optional Linear OAuth (team/project picker), and writes a validated `config.yaml`. Prefer wiring a provider by hand? You need **one** first: `openswarm auth login` (ChatGPT OAuth, used by `codex`/`gpt`), `openswarm auth login --provider openrouter` (or `export OPENROUTER_API_KEY=β¦`), or just have an authenticated `claude` on PATH. Check what's wired with `openswarm auth status`, and diagnose any gaps with `openswarm doctor`.
### What `openswarm init` sets up
The wizard asks three questions, detects what you already have, and writes the config for you:
1. **AI provider** (worker/reviewer) β it auto-detects existing auth and offers inline login:
- `codex-responses` β ChatGPT subscription via OAuth (Codex models, native loop) β **easiest start**
- `codex` β external `codex` CLI Β· `openrouter` β any model (API key/OAuth) Β· `gpt` β OpenAI OAuth
- `lmstudio` / `local` β local servers, no account Β· `claude` β `claude -p` CLI (opt-in fallback)
2. **Task backend** β `local` SQLite issue store (no account) **or** `linear` (OAuth browser login or API key, then an arrow-key **team β project** picker for this repo)
3. **Notification channel** (optional) β `none` / `discord` / `slack` / `telegram` / `webhook`
It then writes **`.env`** (secrets, `chmod 600`), **`config.yaml`** (validated), and β if you mapped a Linear project β **`openswarm.json`** (this repo β Linear team/project). Finally it prints next steps and can launch browser OAuth.
> Re-running in a repo that already has `config.yaml` is refused unless you pass `--force`, and `init` refuses to overwrite a `config.yaml` that symlinks into the daemon's global config. For CI / non-interactive use, `openswarm init --yes` writes a sample config only.
### TUI keyboard shortcuts
| Key | Action |
|-----|--------|
| `Tab` | Switch tabs (Chat / Projects / Tasks / Stuck / Issues / Logs) |
| `Enter` | Send message |
| `Shift+Enter` | Newline |
| `i` | Focus input |
| `Esc` | Exit input focus |
| `Ctrl+C` | Quit |
Status bar shows: provider Β· model Β· message count Β· cumulative cost
---
## CLI Commands
```bash
openswarm # TUI chat (default)
openswarm chat [session] # Simple readline chat
openswarm resume # Reopen the most recent chat session (conversation + goal)
openswarm start # Start full daemon (requires config.yaml)
openswarm run "Fix the bug" -p ~/my-project # Run a single task
openswarm exec "Run tests" --local --pipeline # Execute via daemon
openswarm init # Interactive setup wizard (provider auth, Linear OAuth, config)
openswarm doctor # Diagnose environment (runtime, native deps, providers, ports)
openswarm validate # Validate config.yaml
# Code review
openswarm review # Review the working-tree changes
openswarm review --max # Full-codebase audit: fan reviewer subagents over areas
# β report at .openswarm/audit/ + PM-synthesized Linear
# issues by default (β€10 cohesive, master + sub-issues)
openswarm review --max --fix # after the audit, a worker per flagged area applies the
# fixes in the working tree (review the diff, then commit)
openswarm review --max --concurrency 8 # widen the fan-out β areas auto-split to fill the pool
# more --max flags: --no-linear (report only) Β· --issues-per-area
# (legacy spray) Β· --issues (set parent) Β· --fallback
# Β· --out Β· --dry-run (print the plan)
# CI / test gate auto-fix (npm / Cargo / Python auto-detected)
openswarm fix # Run the checks (package.json scripts, or cargo check+test,
# or ruff/mypy/pytest), fan a fix-worker out over the
# failures, re-run until green
openswarm fix --checks lint,test # only these checks Β· --concurrency Β· --rounds (default 3)
# any language: put {"checks": {"test": "pytest -x"}} in openswarm.json
# Code Registry & BS Detector
openswarm check --scan # Scan repo β register all entities
openswarm check src/foo.ts # File brief (entities, tests, risk)
openswarm check --bs # BS pattern scan (bad code smells)
openswarm check --stats # Registry statistics
openswarm check --high-risk # High-risk entities
openswarm check --search "name" # Full-text search
openswarm annotate "funcName" --deprecate "reason"
openswarm annotate "funcName" --tag "needs-refactor"
openswarm annotate "funcName" --warn "error/security: SQL injection"
```
### `openswarm exec` options
| Option | Description |
|--------|-------------|
| `--path ` | Project path (default: cwd) |
| `--timeout ` | Timeout in seconds (default: 600) |
| `--local` | Execute locally without daemon |
| `--pipeline` | Full pipeline: worker + reviewer + tester + documenter |
| `--worker-only` | Worker only, no review |
| `-m, --model ` | Model override for worker |
Exit codes: `0` success Β· `1` failure Β· `2` timeout
---
## Full Daemon Setup
For autonomous operation (Linear issue processing, Discord control, PR auto-improvement), you need a full config:
### Prerequisites
- **Node.js** >= 22
- **At least one LLM provider**:
- **OpenAI Codex** β `codex-responses` (ChatGPT OAuth, native loop, no extra binary) is the smoothest start; `codex` delegates to the external Codex CLI. `openswarm auth login` handles the ChatGPT OAuth
- **OpenRouter** β any model; `OPENROUTER_API_KEY` or `openswarm auth login --provider openrouter`
- **OpenAI GPT** β `openswarm auth login --provider gpt`
- **Local** β LM Studio (`lmstudio`, `:1234`) or Ollama (`local`, `:11434`), auto-detected, no auth
- **Claude Code CLI** (`claude -p`) β opt-in fallback; an authenticated `claude` on PATH
- **Native build toolchain** β `better-sqlite3` and `@lancedb/lancedb` are native modules. Prebuilt binaries cover common platforms; if yours lacks one, `npm install` builds from source and needs `python3` + a C/C++ toolchain (`build-essential` on Linux, Xcode Command Line Tools on macOS)
- **For autonomous mode only** (optional): **Linear** β sign in with `openswarm auth login --provider linear` (OAuth PKCE) or use an API key + team ID; **Discord** bot token (message content intent); **GitHub CLI** (`gh`) for CI monitoring
### Configuration
After the global install, run the wizard **in the directory you want the daemon to manage** β it writes everything for you:
```bash
openswarm init # writes config.yaml + .env (provider, task backend, notifications)
openswarm doctor # verify providers, native deps, ports
```
See [What `openswarm init` sets up](#what-openswarm-init-sets-up) for the prompts. Prefer to edit by hand? `config.yaml` supports `${VAR}` / `${VAR:-default}` substitution (resolved from `.env`) and is validated with Zod. A minimal `.env` (the wizard writes only what your choices need):
```bash
LINEAR_API_KEY=your-linear-api-key # or: openswarm auth login --provider linear
LINEAR_TEAM_ID=your-linear-team-id
DISCORD_TOKEN=your-discord-bot-token # only if you chose the discord notifier
DISCORD_CHANNEL_ID=your-channel-id
```
### Key configuration sections
| Section | Description |
|---------|-------------|
| `discord` | Bot token, channel ID, webhook URL |
| `linear` | API key, team ID |
| `github` | Repos list for CI monitoring |
| `agents` | Agent definitions (name, projectPath, heartbeat interval) |
| `autonomous` | Schedule, pair mode, role models, decomposition settings |
| `prProcessor` | PR auto-improvement schedule, retry limits, conflict resolver config |
### CLI Adapter (Provider)
```yaml
adapter: codex # one of: codex Β· codex-responses Β· gpt Β· openrouter Β· lmstudio Β· local (default: codex)
```
`adapter` accepts one of the six values below (validated by Zod). For a ChatGPT subscription, `codex-responses` is the smoothest first-run choice β it runs OpenSwarm's native loop over the Responses API with no extra binary. Switch at runtime via Discord, e.g. `!provider codex-responses` / `!provider openrouter`.
| Adapter | Backend | Models | Auth |
|---------|---------|--------|------|
| `codex-responses` | OpenAI Responses API (native loop, no CLI binary) | gpt-5-codex (default), o3, o4-mini | ChatGPT OAuth |
| `codex` | OpenAI Codex CLI (delegated) | gpt-5-codex (default), o3, o4-mini | ChatGPT OAuth / `codex` CLI auth |
| `gpt` | OpenAI Chat API | gpt-4o (default), o3, β¦ | OAuth PKCE |
| `openrouter` | OpenRouter API (native agentic loop) | any OpenRouter model β gpt-5, gemini-2.5, deepseek, glm, qwen, β¦ | `OPENROUTER_API_KEY` or OAuth PKCE |
| `lmstudio` | LM Studio (OpenAI-compatible, local) | loaded LM Studio model (`LMSTUDIO_MODEL`) | None |
| `local` | Ollama (local, auto-detected) | gemma, llama, qwen, mistral, β¦ | None |
> **Claude Code (`claude -p`)** is supported as an **opt-in fallback** (and powers the `claude -p` chat path) β install the `claude` CLI and authenticate it; `openswarm init` and `openswarm doctor` detect it. It is **not** a selectable `adapter:` value.
The `openrouter` adapter runs OpenSwarm's own agentic tool loop (read/search/edit/bash with verification guards), enables ZDR (`data_collection: deny`) for non-OpenAI models, and applies Anthropic prompt caching automatically. Local backends are auto-detected on standard ports (Ollama `:11434`, LM Studio `:1234`); use `lmstudio` for a dedicated LM Studio endpoint (`LMSTUDIO_BASE_URL`, default `http://localhost:1234`).
Per-role adapter overrides (each role may pick its own valid adapter + model):
```yaml
autonomous:
defaultRoles:
worker:
adapter: codex-responses
model: gpt-5-codex
reviewer:
adapter: openrouter
model: anthropic/claude-sonnet-4
```
Optional backlog grooming runs a read-only Planner over the fetched open queue
states for a mapped project (`Todo`, `In Progress`, `In Review`, and `Backlog`)
and compares them with the current repo. Keep `mode: comment` while validating
recommendations; `mode: apply` can update drifted descriptions and move strongly
stale issues to Done.
```yaml
autonomous:
backlogGrooming:
enabled: false
cadenceHours: 24
mode: comment
plannerModel: gpt-5.5
maxIssues: 80
```
### Agent Roles
```yaml
autonomous:
defaultRoles:
worker:
model: gpt-5-codex
escalateModel: openai/gpt-5 # escalate after repeated review failures
escalateAfterIteration: 3
timeoutMs: 1800000
reviewer:
model: gpt-5-codex
timeoutMs: 600000
tester:
enabled: false
documenter:
enabled: false
auditor:
enabled: false
```
### Running the daemon
With the global install, the `openswarm` CLI manages the daemon directly β no repo or `npm run` scripts needed:
```bash
openswarm start # start the daemon in the background
openswarm start --foreground # run attached (logs stream to the terminal)
openswarm status # pid, uptime, log path
openswarm stop # stop the daemon
openswarm dash # open the web dashboard (:3847)
```
> **From source / development** (contributors): clone the repo and use the `npm run β¦` scripts (`npm run dev`, `npm start`, `npm run service:install` for a macOS launchd service, `docker compose up -d`). See [CONTRIBUTING.md](CONTRIBUTING.md).
---
## Architecture
```
ββββββββββββββββββββββββββββ
β Linear API β
β (issues, state, memory) β
βββββββββββββββ¬βββββββββββββ
β
βββββββββββββββββββββββΌββββββββββββββββββββββ
β β β
v v v
ββββββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββββ
β AutonomousRunner β β DecisionEngine β β TaskScheduler β
β (heartbeat loop) ββ>β (scope guard) ββ>β (queue + slots) β
ββββββββββ¬ββββββββββ ββββββββββββββββββββ ββββββββββ¬ββββββββββ
β β
v v
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PairPipeline β
β ββββββββββ ββββββββββββ ββββββββββ βββββββββββββββ β
β β Worker βββ>β Reviewer βββ>β Tester βββ>β Documenter β β
β β(Adapterβ<βββ(Adapter) β β(Adapterβ β (Adapter) β β
β βββββ¬βββββ ββββββββββββ ββββββββββ βββββββββββββββ β
β β β StuckDetector β
β βββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Adapters: Codex | GPT | OpenRouter | Local (Ollama) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β β
v v v
ββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββββ
β Discord Bot β β Memory (LanceDB β β Knowledge Graph β
β (commands) β β + Xenova E5) β β (code analysis) β
ββββββββββββββββ ββββββββββββββββββββ ββββββββββ¬ββββββββββ
β
ββββββββββ΄ββββββββββ
β Code Registry β
β (SQLite + FTS5) β
β + BS Detector β
ββββββββββββββββββββ
```
## Features
- **Multi-Provider Adapters** β Pluggable adapter system: **OpenAI Codex/GPT**, **OpenRouter** (any model, native agentic loop), **local models** (Ollama, LM Studio), and **Claude Code** (`claude -p`, opt-in) with runtime provider switching
- **Code Registry** β SQLite-backed entity registry tracking every function/class/type across 8 languages, with complexity scoring, test mapping, and risk assessment
- **BS Detector** β Built-in static analysis engine that detects bad code patterns (empty catch, hardcoded secrets, `as any`, etc.) with pipeline guard integration
- **Autonomous Pipeline** β Cron-driven heartbeat fetches Linear issues, runs Worker/Reviewer pair loops, and updates issue state automatically
- **Worker/Reviewer Pairs** β Multi-iteration code generation with automated review, testing, and documentation stages
- **Codebase Audit (`review --max`)** β fans reviewer subagents out over directory-shaped areas (auto-split to fill `--concurrency`), aggregates a deduped verdict into a markdown report, and synthesizes β€10 cohesive Linear issues via a PM agent. `--fix` sends a worker per flagged area to apply the fixes in the working tree. Language-agnostic; codex usage-limit aware with automatic `claude` fallback
- **CI / test gate auto-fix (`openswarm fix`)** β runs the project's objective checks (lint / typecheck / build / test), groups the failures by file into areas, fans a fix-worker out over each, then **re-runs the checks and repeats until green** (or the round budget). Deterministic convergence β unlike the review fix pass, it verifies its own work. Multi-language: auto-detects npm scripts, `Cargo.toml` (`cargo check`/`test`, clippy on request), and Python tooling (`ruff`/`mypy`/`pytest`, gated on the repo's config); any other toolchain via a `"checks"` map in `openswarm.json`
- **Decision Engine** β Scope validation, rate limiting, priority-based task selection, and workflow mapping
- **Cognitive Memory** β LanceDB vector store with Xenova/multilingual-e5-base embeddings for long-term recall across sessions
- **Repo Knowledge Loop** β workers learn each repository over time: task outcomes (success patterns, review-rejection pitfalls) are stored per-repo and recalled into the next worker prompt
- **SWE-bench Verified** β the agentic harness solves real SWE-bench Lite issues, graded by the official harness; hybrid mode (frontier diagnosis + lightweight implementer) resolved 3/3 attempted instances ([benchmarks/RUBRIC.md](benchmarks/RUBRIC.md))
- **Knowledge Graph** β Static code analysis, dependency mapping, impact analysis, and file-level conflict detection across concurrent tasks
- **Discord Control** β Full command interface for monitoring, task dispatch, scheduling, provider switching, and pair session management
- **Rich TUI Chat** β Claude Code inspired terminal interface with tabs, streaming responses, and geek-themed loading messages
- **Dynamic Scheduling** β Cron-based job scheduler with Discord management commands
- **PR Auto-Improvement** β Monitors open PRs, auto-fixes CI failures, auto-resolves merge conflicts, and retries until all checks pass
- **Long-Running Monitors** β Track external processes (training jobs, batch tasks) and report completion
- **Web Dashboard** β Real-time pipeline stages, cost tracking, worktree status, and live logs on port 3847
- **Pace Control** β 5-hour rolling window task caps, per-project limits, turbo mode, exponential backoff on failures
- **i18n** β English and Korean locale support
---
## How It Works
```
Linear (Todo/In Progress)
β Fetch assigned issues
β DecisionEngine filters & prioritizes
β Resolve project path via projectMapper
β PairPipeline.run()
β Worker generates code (via the configured adapter)
β Reviewer evaluates (APPROVE/REVISE/REJECT)
β Loop up to N iterations
β Optional: Tester β Documenter stages
β Update Linear issue state (Done/Blocked)
β Report to Discord
β Save to cognitive memory
```
### Memory System
Hybrid retrieval: `0.55 Γ similarity + 0.20 Γ importance + 0.15 Γ recency + 0.10 Γ frequency`
Memory types: `belief` Β· `strategy` Β· `user_model` Β· `system_pattern` Β· `constraint`
Background: decay, consolidation, contradiction detection, distillation.
**Repo knowledge loop** β every completed task writes repo-scoped knowledge
(success β `system_pattern` with files changed + approach, review rejection β
`constraint` pitfall), and the next task on the same repo recalls the most
relevant entries into the worker prompt as a "Repository Knowledge" section.
Workers get better at a codebase the more they work on it. Workers can also actively query accumulated repo knowledge mid-task via the `search_memory` tool.
### Benchmarks (L0βL6)
`benchmarks/` contains a difficulty ladder for routing models by measured
capability β synthetic L0βL5 tasks with deterministic grading, and L6 = real
GitHub issues (SWE-bench Lite) solved by the OpenSwarm harness and graded by
the official swebench harness. Headline: **hybrid mode** (frontier read-only
diagnosis + lightweight implementer with a verification loop) resolved 3/3
attempted instances that every single lightweight model had failed. See
[benchmarks/RUBRIC.md](benchmarks/RUBRIC.md) for the rubric, measured results,
and the harness defects the benchmark uncovered.
---
## Discord Commands
### Task Dispatch
| Command | Description |
|---------|-------------|
| `!dev ""` | Run a dev task on a repository |
| `!dev list` | List known repositories |
| `!tasks` | List running tasks |
| `!cancel ` | Cancel a running task |
### Agent Management
| Command | Description |
|---------|-------------|
| `!status` | Agent and system status |
| `!pause ` | Pause autonomous work |
| `!resume ` | Resume autonomous work |
| `!log [lines]` | View recent output |
### Linear Integration
| Command | Description |
|---------|-------------|
| `!issues` | List Linear issues |
| `!issue ` | View issue details |
| `!limits` | Agent daily execution limits |
### Autonomous Execution
| Command | Description |
|---------|-------------|
| `!auto` | Execution status |
| `!auto start [cron] [--pair]` | Start autonomous mode |
| `!auto stop` | Stop autonomous mode |
| `!auto run` | Trigger immediate heartbeat |
| `!approve` / `!reject` | Approve or reject pending task |
### Worker/Reviewer Pair
| Command | Description |
|---------|-------------|
| `!pair` | Pair session status |
| `!pair start [taskId]` | Start a pair session |
| `!pair run [project]` | Direct pair run |
| `!pair stop [sessionId]` | Stop a pair session |
| `!pair history [n]` | View session history |
| `!pair stats` | View pair statistics |
### Scheduling
| Command | Description |
|---------|-------------|
| `!schedule` | List all schedules |
| `!schedule run ` | Run a schedule immediately |
| `!schedule toggle ` | Enable/disable a schedule |
| `!schedule add ""` | Add a schedule |
| `!schedule remove ` | Remove a schedule |
### Other
| Command | Description |
|---------|-------------|
| `!ci` | GitHub CI failure status |
| `!provider ` | Switch CLI provider at runtime |
| `!codex` | Recent session records |
| `!memory search ""` | Search cognitive memory |
| `!help` | Full command reference |
---
## Project Structure
```
src/
βββ index.ts # Entry point
βββ cli.ts # CLI entry point (run, exec, chat, init, validate, start)
βββ cli/ # CLI subcommand handlers
β βββ promptHandler.ts # exec command: daemon submit, auto-start, polling
βββ core/ # Config, service lifecycle, types, event hub
βββ adapters/ # Provider adapters (codex, codex-responses, gpt, openrouter, local, lmstudio), agentic loop
βββ agents/ # Worker, reviewer, tester, documenter, auditor
β βββ pairPipeline.ts # Worker β Reviewer β Tester β Documenter pipeline
β βββ agentBus.ts # Inter-agent message bus
β βββ cliStreamParser.ts # Claude CLI output parser
βββ orchestration/ # Decision engine, task parser, scheduler, workflow
βββ automation/ # Autonomous runner, cron scheduler, PR processor
βββ memory/ # LanceDB + Xenova embeddings cognitive memory
βββ knowledge/ # Code knowledge graph (scanner, analyzer, graph)
βββ registry/ # Code entity registry, BS detector, entity scanner
βββ issues/ # Local issue tracker (SQLite + GraphQL + Kanban UI)
βββ discord/ # Bot core, command handlers, pair session UI
βββ linear/ # Linear SDK wrapper, project updater
βββ github/ # GitHub CLI wrapper for CI monitoring
βββ support/ # Web dashboard, planner, rollback, git tools
βββ locale/ # i18n (en/ko) with prompt templates
βββ __tests__/ # Vitest test suite
```
## State & Data
| Path | Description |
|------|-------------|
| `~/.openswarm/` | State directory (memory, codex, metrics, workflows) |
| `~/.openswarm/registry.db` | Code entity registry (SQLite) |
| `~/.openswarm/issues.db` | Local issue tracker (SQLite) |
| `~/.claude/openswarm-*.json` | Pipeline history and task state |
| `~/.config/openswarm/telemetry.json` | Anonymous install id + opt-out notice flag |
| `config.yaml` | Main configuration |
| `dist/` | Compiled output |
---
## Privacy & Telemetry
OpenSwarm collects **anonymous, opt-out** usage telemetry to understand how it's
actually used (npm downloads and GitHub stars don't tell us). A single event is
sent per command invocation.
**What is sent** (and nothing else):
| Field | Example | Why |
|-------|---------|-----|
| Random install id | `V1StGXR8_Z5j...` (nanoid) | De-duplicate installs β anonymous, local-only |
| Command | `start`, `run`, `chat` | Which features are used |
| Version | `0.9.3` | Version adoption |
| OS / arch | `darwin` / `arm64` | Platform support priorities |
| Node version | `22.3.0` | Runtime support |
| Adapter family | `codex` | Which providers are popular |
| Error flag | `0` / `1` | Failure rate (boolean only) |
**Never sent:** source code, prompts, file paths, repo or issue names, Linear/Discord
content, environment variables, API keys, or any personal data.
**How to opt out** (any one):
```bash
export OPENSWARM_TELEMETRY=0 # or DO_NOT_TRACK=1
```
```yaml
# config.yaml
telemetry:
enabled: false
```
CI environments (`CI` / `GITHUB_ACTIONS`) are excluded automatically. The collector
is a Cloudflare Worker writing to a private D1 table; telemetry never blocks or slows
the CLI (fire-and-forget with a short timeout, and failures are silently ignored).
## Tech Stack
| Category | Technology |
|----------|-----------|
| Runtime | Node.js 22+ (ESM) |
| Language | TypeScript (strict mode) |
| Build | tsc |
| Agent Execution | Claude Code, OpenAI GPT/Codex, Ollama/LMStudio/llama.cpp |
| Local DB | better-sqlite3 (WAL mode, FTS5) |
| Task Management | Linear SDK (`@linear/sdk`) |
| Communication | Discord.js 14 |
| Vector DB | LanceDB + Apache Arrow |
| Embeddings | Xenova/transformers (multilingual-e5-base, 768D) |
| Scheduling | Croner |
| Config | YAML + Zod validation |
| Linting | oxlint |
| Testing | Vitest |
---
## Changelog
Full version history lives in **[CHANGELOG.md](CHANGELOG.md)** and the
[GitHub Releases](https://github.com/unohee/OpenSwarm/releases) page.
Latest β **v0.17.5**: a repeating reviewer now triggers a one-shot worker
escalation (higher model and/or `high` effort) before the session gives up β
on top of v0.17.4's cross-session feedback persistence and fan-out
dirty-promotion fix, and v0.17.3's duplicate-daemon prevention. See
CHANGELOG.md for the rest.
---
## Troubleshooting
### Korean / multibyte input doubles over mobile SSH (e.g. Termius)
If the chat TUI shows each Hangul (or other multibyte) character twice β
`μ΄μ΄λ λ κ² μ°μ°μ΄λκ²` β while ASCII characters look fine, the cause is almost
always **client-side local / predictive echo** in the mobile SSH app drawing an
extra copy of wide characters. The keystroke reaches OpenSwarm once; the terminal
paints it twice.
Fix it in the SSH client:
- **Termius** β Host/Terminal settings β turn **Local Echo** (a.k.a. predictive
echo) **off**, and ensure the encoding is **UTF-8**.
- Confirm the server side is fine by running with diagnostics:
```bash
OPENSWARM_DEBUG_INPUT=1 openswarm chat
```
Type a few Korean characters, then inspect `~/.openswarm/input-debug.log`. If a
single keypress logs **one** code point (`cp=[51060]`) but you saw two glyphs,
the doubling is terminal echo (client-side). If it logs the code point **twice**
in one event, it's an app-level issue β please attach the log to
[a bug report](https://github.com/unohee/OpenSwarm/issues/new?template=bug_report.md).
---
## Contributing
Contributions are welcome β OpenSwarm is MIT-licensed and accepts pull requests from anyone. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for development setup, the local check gates, branch/commit conventions, and the PR process. By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
- π [Report a bug](https://github.com/unohee/OpenSwarm/issues/new?template=bug_report.md)
- π‘ [Share an idea](https://github.com/unohee/OpenSwarm/discussions) β the roadmap is built in the open
- π§ Fork the repo, branch from `main`, and open a PR (CI runs lint β typecheck β build β test)
- π Found a security issue? See [SECURITY.md](SECURITY.md) β please don't file it publicly
---
## License
[MIT](LICENSE) Β© Heewon Oh