Status bar shows: provider · model · message count · cumulative cost

CLI Commands

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                   # Generate config.yaml scaffold
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 <path> | Project path (default: cwd) | | --timeout <seconds> | 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> | 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
• Claude Code CLI authenticated (claude -p) — default provider
• OpenAI Codex CLI (codex exec) — optional alternative provider
• Discord Bot token with message content intent
• Linear API key and team ID
• GitHub CLI (gh) for CI monitoring (optional)

Configuration

git clone https://github.com/unohee/OpenSwarm.git
cd OpenSwarm
npm install
cp config.example.yaml config.yaml

Create a .env file:

DISCORD_TOKEN=your-discord-bot-token
DISCORD_CHANNEL_ID=your-channel-id
LINEAR_API_KEY=your-linear-api-key
LINEAR_TEAM_ID=your-linear-team-id

config.yaml supports ${VAR} / ${VAR:-default} substitution and is validated with Zod schemas.

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)

adapter: claude   # "claude" | "codex" | "gpt" | "local"

Switch at runtime via Discord: !provider codex / !provider claude

| Adapter | Backend | Models | Auth | |---------|---------|--------|------| | claude | Claude Code CLI | sonnet-4, haiku-4.5, opus-4 | CLI auth | | codex | OpenAI Codex CLI | o3, o4-mini | CLI auth | | gpt | OpenAI API | gpt-4o, o3, gpt-4.1 | OAuth PKCE | | local | Ollama / LMStudio / llama.cpp | gemma4, llama3, mistral, qwen, etc. | None |

Local models are auto-detected on standard ports (Ollama :11434, LMStudio :1234, llama.cpp :8080).

Per-role adapter overrides:

autonomous:
  defaultRoles:
    worker:
      adapter: codex
      model: o4-mini
    reviewer:
      adapter: claude
      model: claude-sonnet-4-20250514

Agent Roles

autonomous:
  defaultRoles:
    worker:
      model: claude-haiku-4-5-20251001
      escalateModel: claude-sonnet-4-20250514
      escalateAfterIteration: 3
      timeoutMs: 1800000
    reviewer:
      model: claude-haiku-4-5-20251001
      timeoutMs: 600000
    tester:
      enabled: false
    documenter:
      enabled: false
    auditor:
      enabled: false

Running the daemon

macOS launchd service (recommended)

npm run service:install    # Build and install as system service
npm run service:start      # Start
npm run service:stop       # Stop
npm run service:restart    # Restart
npm run service:status     # Status and recent logs
npm run service:logs       # stdout (follow mode)
npm run service:errors     # stderr (follow mode)
npm run service:uninstall  # Uninstall

Manual

npm run build && npm start   # Production
npm run dev                  # Development (tsx watch)
docker compose up -d         # Docker

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: Claude | Codex | GPT | Local (Ollama/LMS)   │  │
  │  └────────────────────────────────────────────────────────┘  │
  └──────────────────────────────────────────────────────────────┘
           │                     │                     │
           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: Claude Code, OpenAI GPT/Codex, and local models (Ollama, LMStudio, llama.cpp) 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
• Knowledge Graph — Static code analysis, dependency mapping, impact analysis, and file-level confl