OpenSwarm

Autonomous AI agent orchestrator powered by Claude Code CLI

OpenSwarm orchestrates multiple Claude Code instances as autonomous agents. It picks up Linear issues, runs Worker/Reviewer pair pipelines to produce code changes, reports progress to Discord, and retains long-term memory via LanceDB vector embeddings.

📸 Demo

Web Dashboard (Port 3847)

Real-time supervisor dashboard with repository status, pipeline events, live logs, PR processor, and agent chat.

CLI Chat Interface

Rich TUI Mode (Claude Code inspired):

$ openswarm chat --tui

Dark theme with Claude Code inspired color palette
5 interactive tabs: Chat, Projects, Tasks, Stuck, Logs
Real-time streaming responses with themed loading messages
Keyboard shortcuts: Tab (switch tabs), Enter (send), Shift+Enter (newline), Esc (exit input)
Session management: auto-save, resume, model switching
Status bar: model, message count, cumulative cost

Simple Mode (readline based):

$ openswarm chat [session-name]

╔════════════════════════════════════╗
║  Swarm Chat  sonnet-4-5           ║
╚════════════════════════════════════╝
demo | /help | Ctrl+D exit

you What are the main components of OpenSwarm?
assistant OpenSwarm has 9 main architectural layers... ($0.0023)

you /model haiku
Model: claude-haiku-4-5-20251001

you /save openswarm-overview
Saved: openswarm-overview

Commands: /clear, /model <name>, /save [name], /help

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 > openswarm.log 2>&1 &

Docker

docker compose up -d

Shell Helper (optional)

Add to ~/.zshrc or ~/.bashrc:

openswarm() {
  case "$1" in
    start)
      cd /path/to/OpenSwarm && nohup npm start > ~/.openswarm/log 2>&1 &
      echo "✅ Started (PID: $!)"
      ;;
    stop)
      pkill -f "openswarm" && echo "✅ Stopped"
      ;;
    status)
      pgrep -f "openswarm" && echo "✅ Running" || echo "❌ Stopped"
      ;;
    chat)
      cd /path/to/OpenSwarm && node --import=tsx src/cli.ts chat "${@:2}"
      ;;
  esac
}

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/                # CLI provider adapters (claude, codex), process registry
├── 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
│   ├── autonomousRunner.ts  # Cron-driven heartbeat and task dispatch
│   ├── prProcessor.ts       # PR auto-improvement (CI fixes, conflict resolution)
│   ├── conflictResolver.ts  # AI-powered merge conflict resolution
│   ├── prOwnership.ts       # Bot PR tracking for conflict resolution
│   ├── longRunningMonitor.ts# External process monitoring
│   └── runnerState.ts       # Persistent pipeline state
├── memory/                  # LanceDB + Xenova embeddings cognitive memory
├── knowledge/               # Code knowledge graph (scanner, analyzer, graph)
├── 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

Discord Commands

Task Dispatch

Command	Description
`!dev <repo> "<task>"`	Run a dev task on a repository
`!dev list`	List known repositories
`!tasks`	List running tasks
`!cancel <taskId>`	Cancel a running task

Agent Management

Command	Description
`!status`	Agent and system status
`!pause <session>`	Pause autonomous work
`!resume <session>`	Resume autonomous work
`!log <session> [lines]`	View recent output

Linear Integration

Command	Description
`!issues`	List Linear issues
`!issue <id>`	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 <taskId> [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 <name>`	Run a schedule immediately
`!schedule toggle <name>`	Enable/disable a schedule
`!schedule add <name> <path> <interval> "<prompt>"`	Add a schedule
`!schedule remove <name>`	Remove a schedule

Other

Command	Description
`!ci`	GitHub CI failure status
`!provider <claude\|codex>`	Switch CLI provider at runtime
`!codex`	Recent session records
`!memory search "<query>"`	Search cognitive memory
`!help`	Full command reference

How It Works

Issue Processing Flow

Linear (Todo/In Progress)
  → Fetch assigned issues
  → DecisionEngine filters & prioritizes
  → Resolve project path via projectMapper
  → PairPipeline.run()
    → Worker generates code (Claude CLI)
    → 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 scoring: 0.55 * similarity + 0.20 * importance + 0.15 * recency + 0.10 * frequency

Memory types: belief, strategy, user_model, system_pattern, constraint

Background cognition: decay, consolidation, contradiction detection, and distillation (noise filtering).

Tech Stack

Category	Technology
Runtime	Node.js 22+ (ESM)
Language	TypeScript (strict mode)
Build	tsc
Agent Execution	Claude Code CLI (`claude -p`) or OpenAI Codex CLI (`codex exec`) via pluggable adapters
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

State & Data

Path	Description
`~/.openswarm/`	State directory (memory, codex, metrics, workflows, etc.)
`~/.claude/openswarm-*.json`	Pipeline history and task state
`config.yaml`	Main configuration
`dist/`	Compiled output

Docker

docker compose up -d

The Docker setup includes volume mounts for ~/.openswarm/ state persistence and .env for secrets.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
.claude/agents		.claude/agents
.github/workflows		.github/workflows
docs		docs
screenshots		screenshots
scripts		scripts
src		src
templates		templates
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
HEARTBEAT.md		HEARTBEAT.md
LICENSE		LICENSE
README.md		README.md
config.example.json		config.example.json
config.example.yaml		config.example.yaml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

OpenSwarm

📸 Demo

Web Dashboard (Port 3847)

CLI Chat Interface

Architecture

Features

Prerequisites

Installation

Configuration

Key Configuration Sections

CLI Adapter (Provider)

Agent Roles

Usage

CLI Commands

openswarm exec Options

Running the Service

macOS launchd Service (Recommended)

Manual Execution

Docker

Shell Helper (optional)

Project Structure

Discord Commands

Task Dispatch

Agent Management

Linear Integration

Autonomous Execution

Worker/Reviewer Pair

Scheduling

Other

How It Works

Issue Processing Flow

Memory System

Tech Stack

State & Data

Docker

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`openswarm exec` Options

Packages