Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

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 9 hours ago
JSON representation

OpenSwarm β€” Autonomous AI dev team orchestrator powered by Claude Code CLI. Discord control, Linear integration, cognitive memory.

Awesome Lists containing this project

README 

          
# OpenSwarm



[![npm version](https://img.shields.io/npm/v/@intrect/openswarm.svg)](https://www.npmjs.com/package/@intrect/openswarm)

[![npm downloads](https://img.shields.io/npm/dm/@intrect/openswarm.svg)](https://www.npmjs.com/package/@intrect/openswarm)

[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

[![SWE-bench Lite](https://img.shields.io/badge/SWE--bench_Lite-hybrid_3%2F3_resolved-2ea44f)](benchmarks/RUBRIC.md)

[![GitHub Discussions](https://img.shields.io/github/discussions/unohee/OpenSwarm?logo=github&label=discussions)](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 Chat Interface](screenshots/tui.png)



### 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 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 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

```



### 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

- **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.



### 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.yaml` | Main configuration |

| `dist/` | Compiled output |



---



## 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



### v0.8.1

- **License** β€” relicensed to **MIT** (was GPL-3.0)

- **Docs** β€” README overhauled for first-time users (`openswarm init` walkthrough, accurate adapter registry, latest-build models) and contributor health files added (CONTRIBUTING, Code of Conduct, Security policy, PR template)



### v0.8.0

- **Interactive `openswarm init` wizard** β€” Linear OAuth (PKCE) sign-in with arrow-key team/project picker, provider auto-detection, and a validated `config.yaml` (INT-1808)

- **`openswarm doctor`** β€” one-shot environment diagnostics: Node version, native modules, provider CLIs, ports, and config discovery

- **Linear OAuth login** β€” `openswarm auth login --provider linear` (PKCE, no API-key entry)

- **CLI polish** β€” ASCII banner and colored output (NO_COLOR / non-TTY aware)

- **Autonomy hardening** β€” dependency-order gating + Backlog parking (INT-1809), daemon self-modify guards (INT-1810), `jobProfiles` partial roles carried through to runtime (INT-1812), and an `init` symlink guard that refuses to overwrite the daemon's global config

- **Fix** β€” codex adapter `--full-auto` β†’ `--sandbox workspace-write` (codex 0.137 deprecation) (INT-1699)



### v0.5.0

- **Native Codex Responses-API adapter** (`codex-responses`) β€” ChatGPT OAuth, no CLI binary required; live model discovery via the OAuth backend

- **Linear-optional autonomy** β€” `ITaskSource` abstraction + local SQLite task source; the autonomous runner no longer requires Linear

- **Notifier abstraction** β€” Discord / Slack / Telegram / webhook

- **Agentic loop tools** β€” `web_fetch` + `web_search`

- **Planner cockpit TUI** β€” `/plan` decompose β†’ approve β†’ dispatch

- **Loop maturity (INT-1679)** β€” bad-edit guard + reflection self-repair loop

- **Conflict-free concurrency (INT-1610)** β€” blocker/dependency ordering for parallel workers; worker instructions + actions logged to issue comments



### v0.4.0

- **Benchmarks (L0–L6)** β€” difficulty rubric, model-routing benchmark, and a real SWE-bench harness

- **Repo knowledge loop** β€” workers learn each repository across tasks (per-repo success patterns + review-rejection pitfalls recalled into prompts)

- **OpenRouter agentic adapter** β€” native tool loop with harness hardening from SWE-bench findings

- **LM Studio adapter** with auto model selection

- **CLI** β€” `openswarm dash`, `--tree` / `--ci` flags for `check`



### v0.3.0

- **Code Registry**: `openswarm check --scan` scans repo, registers 1000+ entities across 8 languages (TS, Python, Go, Rust, Java, C, C++, C#) with test mapping, complexity scoring, and risk assessment

- **BS Detector**: `openswarm check --bs` β€” built-in static analysis for bad code patterns, pipeline guard integration

- **Local Model Support**: Ollama, LMStudio, llama.cpp via single `local` adapter with auto-detection

- **GPT Adapter**: OpenAI models via OAuth PKCE flow

- **Local Issue Tracker**: SQLite + GraphQL + Kanban web UI at `:3847/issues`

- **CLI**: `openswarm check`, `openswarm annotate` commands



### v0.2.2

- `openswarm` without arguments now launches TUI chat directly



### v0.2.1

- Security: patched lodash, picomatch, rollup, undici, yaml vulnerabilities



### v0.2.0

- Published as `@intrect/openswarm` on npm

- Extracted `@intrect/claude-driver` as standalone zero-dependency package

- Autonomous runner hardening and multi-project orchestration

- Task-state rehydration from Linear comments

- `--verbose` flag for detailed execution logging

- Codex adapter: dropped o-series model override



### v0.1.0

- Initial release

- Worker/Reviewer pair pipeline

- Claude Code CLI + Codex CLI adapters

- Discord bot control

- Linear integration

- LanceDB cognitive memory

- Web dashboard (port 3847)

- Rich TUI chat interface



---



## 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