Skip to content

unohee/OpenSwarm

BranchesTags

Repository files navigation

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.

Quick Start

npm install -g @intrect/openswarm
openswarm

That's it. openswarm with no arguments launches the TUI chat interface immediately.

TUI Chat Interface

TUI keyboard shortcuts

Key Action
Tab Switch tabs (Chat / Projects / Tasks / Stuck / 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

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

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" (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:

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                                      │
  │  ┌───┴────────────────────────────────────────────────────┐  │
  │  │ 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

How It Works

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

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

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
├── 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

State & Data

Path Description
~/.openswarm/ State directory (memory, codex, metrics, workflows)
~/.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 CLI (claude -p) or OpenAI Codex CLI (codex exec)
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.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

License

MIT

About

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

Topics

devops typescript discord-bot multi-agent pair-programming linear orchestrator autonomous-agents ai-agents claude vector-database llm ai-coding claude-code

Resources

Readme

License

MIT license
Activity

Stars

342 stars

Watchers

3 watching

Forks

45 forks
Report repository

Releases 1

v0.1.0 — Initial Public Release Latest
Mar 9, 2026

Packages

 
 
 

Contributors

Languages