codeswarm

flowchart TD
    A[GitHub Issue<br/>ai:ready] --> B[Planner<br/>decomposes to JSON]
    B --> C1[Researcher]
    B --> C2[Coder]
    B --> C3[Tester]
    C1 --> D[Worktrees<br/>.codeswarm/task-xxx]
    C2 --> D
    C3 --> D
    D --> E[Tester<br/>npm test / typecheck / lint]
    E -->|fail| C2
    E -->|pass| F[Reviewer<br/>security + correctness]
    F -->|changes| C2
    F -->|approved| G[GitHub PR]
    G --> H{CI}
    H -->|pass| I[Ready to merge]
    H -->|fail| J[CI Agent<br/>parse logs → fix → push]
    J --> H

GitHub Issue (ai:ready)
  ↓ Planner → { goal, tasks: [...] }
  ├─ Researcher → finds files, git history, plan
  ├─ Coder ×N → isolated worktrees → commits
  └─ Tester → npm test / lint / typecheck
       ↓ fail → Coder
       ↓ pass → Reviewer
            ↓ changes → Coder
            ↓ approved → GitHub PR → CI → CI Agent fixes on fail → Ready

npx codeswarm init

DATABASE_URL=file:./data/codeswarm.db
GITHUB_TOKEN=ghp_xxx
GITHUB_OWNER=your-org
GITHUB_REPO=your-repo
OPENAI_API_KEY=sk-xxx
# or ANTHROPIC_API_KEY=sk-ant-xxx
# TELEGRAM_BOT_TOKEN=xxx
# TELEGRAM_CHAT_ID=xxx

docker-compose up --build
# API: http://localhost:3000
# Dashboard: http://localhost:3001

npm install
npm run build
npm run dev
# or
node apps/api/dist/index.js &
node apps/dashboard/dist/index.js

codeswarm issue run 421 --mock
# ✅ Local pipeline done: completed PR: https://github.com/example/repo/pull/438

codeswarm issue run 421
codeswarm issue plan 421   # plan only, no code

codeswarm init                  # init codeswarm.yml + .env
codeswarm run --mock            # start API + worker hint
codeswarm issue run <num> [--mock] [--repo owner/repo]
codeswarm issue plan <num>      # planner only
codeswarm pr review <num>
codeswarm pr fix <num>          # CI fix loop
codeswarm status                # ASCII dashboard in terminal
codeswarm agents
codeswarm queue
codeswarm mcp                   # MCP server over stdio

GitHub
  │ webhook / poller
  ▼
Orchestrator ──► Task Queue ──► Agents (×N) ──► Git Worktrees ──► Tests / CI ──► GitHub PR
  │                 │                │
  │                 │                ├─ Planner / Researcher / Coder / Tester / Reviewer / CI Agent
  │                 │                └─ WorktreeManager + ConflictResolver
  │                 └─ InMemory (MVP) / Redis + BullMQ (prod)
  └─ projects / tasks / agents / worktrees / artifacts / pull_requests / reviews / costs / agent_events
     SQLite (MVP) → PostgreSQL (v0.3)

codeswarm/
├── apps/
│   ├── api/          # HTTP API, webhook, orchestrator
│   ├── worker/       # queue worker (scale horizontally)
│   └── dashboard/    # real-time Web UI
├── packages/
│   ├── core/         # types, state-machine, cost, DB schema
│   ├── llm/          # OpenAI/Anthropic/Google/Ollama/LiteLLM/Mock
│   ├── agents/       # 6 agents + orchestrator
│   ├── github/       # Issues/PRs/Comments/Checks
│   ├── git/          # worktree manager
│   ├── queue/        # InMemory / Redis
│   ├── sandbox/      # security
│   ├── mcp/          # MCP server
│   └── telegram/     # notifier
├── tests/            # vitest (15 tests)
├── examples/         # wallet race condition
└── docker/

{
  "mcpServers": {
    "codeswarm": { "command": "npx", "args": ["codeswarm", "mcp"] }
  }
}

┌─────────────────────────────────────────┐
│ CODESWARM                               │
├─────────────────────────────────────────┤
│ ACTIVE AGENTS: 7                        │
│ QUEUE: 12                               │
│ PRs TODAY: 8                            │
│ SUCCESS RATE: 81%                       │
├─────────────────────────────────────────┤
│ #421 Wallet race condition   ██████ 80% │
│ #422 API timeout             ████░░ 55% │
└─────────────────────────────────────────┘

task:
  max_agents: 4
  max_retries: 3
  max_cost_usd: 2.00
  timeout_minutes: 30
swarm:
  max_total_agents: 10
  max_depth: 2
llm:
  provider: openai # openai | anthropic | openrouter | google | ollama | litellm
  model: gpt-4o-mini
  temperature: 0.2
queue:
  type: memory # or redis
  redisUrl: redis://localhost:6379
sandbox:
  enabled: true
  network: restricted
  filesystem: repository_only

gantt
    title CodeSwarm — Timeline
    dateFormat  YYYY-MM-DD
    axisFormat %b %Y
    section MVP
    v0.1 shipped    :done, v01, 2026-09-01, 2026-09-01
    section Scale
    v0.2 Parallel   :done, v02, 2026-09-01, 2026-09-02
    section Depth
    v0.3 Plugins    :done, v03, 2026-09-02, 2026-09-03
    section GA
    v1.0 Platform   :done, v10, 2026-09-03, 2026-09-04

npm install
npm run build   # tsc -b
npm test        # vitest — 15 tests