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                                      │
  │  ┌───┴────────────────────────────────────────────────────┐  │
  │  │ CLI Adapters: Claude (`claude -p`) | Codex (`codex`)   │  │
  │  └────────────────────────────────────────────────────────┘  │
  └──────────────────────────────────────────────────────────────┘
           │                     │                     │
           v                     v                     v
  ┌──────────────┐  ┌──────────────────┐  ┌──────────────────┐
  │  Discord Bot │  │  Memory (LanceDB │  │  Knowledge Graph │
  │  (commands)  │  │  + Xenova E5)    │  │  (code analysis) │
  └──────────────┘  └──────────────────┘  └──────────────────┘

Features

• Multi-Provider Adapters - Pluggable CLI adapter system supporting Claude Code (claude -p) and OpenAI Codex (codex exec), with runtime provider switching via Discord command
• 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 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

Prerequisites

• Node.js >= 22
• CLI Provider (at least one):
  • Claude Code CLI installed and authenticated (claude -p) — default provider
  • OpenAI Codex CLI installed (codex exec) — alternative provider
• Discord Bot token with message content intent
• Linear API key and team ID
• GitHub CLI (gh) for CI monitoring (optional)

Installation

git clone https://github.com/unohee/OpenSwarm.git
cd OpenSwarm
npm install

Configuration

cp config.example.yaml config.yaml

Create a .env file with required secrets:

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 environment variable substitution (${VAR} or ${VAR:-default}) 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)

OpenSwarm supports multiple CLI backends. Set the default in config.yaml:

adapter: claude   # "claude" (default) or "codex"

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

| Adapter | CLI Command | Models | Git Management | |---------|-------------|--------|----------------| | claude | claude -p | claude-sonnet-4, claude-haiku-4.5, claude-opus-4 | Manual (worker commits) | | codex | codex exec | o3, o4-mini | Auto (--full-auto) |

Per-role adapter overrides are supported — e.g., use Codex for workers and Claude for reviewers:

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

Agent Roles

Each pipeline stage can be configured independently:

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

Usage

CLI Commands

# Interactive chat with Claude (TUI mode)
openswarm chat --tui

# Interactive chat (simple readline mode)
openswarm chat [session-name]

# Run a single task (no config needed)
openswarm run "Fix the login bug" --path ~/my-project

# Execute via daemon (auto-starts service if needed)
openswarm exec "Run tests and fix failures" --worker-only
openswarm exec "Review all pending PRs" --timeout 300
openswarm exec "Fix CI" --local --pipeline

# Initialize configuration
openswarm init

# Validate configuration
openswarm validate

# Start the full daemon
openswarm start

openswarm exec Options

| Option | Description | |--------|-------------| | --path <path> | Project path (default: cwd) | | --timeout <seconds> | Timeout in seconds (default: 600) | | --no-auto-start | Do not auto-start the service | | --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).

Running the Service

macOS launchd Service (Recommended)

Installation:

# Build and install as a system service
npm run service:install

Service Management:

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

Browser Auto-Launch (Optional):

npm run browser:install    # Auto-open dashboard on boot
npm run browser:uninstall  # Disable auto-open

The service will:

• Auto-start on system boot
• Auto-restart on crash
• Log to ~/.openswarm/logs/
• Run with your user permissions (access to Claude CLI, gh, local files)
• (Optional) Open web dashboard at http://localhost:3847 on boot

Manual Execution

# Development
npm run dev

# Production
npm run build
npm start

# Background (legacy)
nohup npm start > ope