<p align="center">
  <h1 align="center">CodeSwarm</h1>
  <p align="center"><strong>Turn GitHub issues into tested, reviewed pull requests — autonomously.</strong></p>
  <p align="center">Self-hosted, multi-agent AI engineering swarm for GitHub. Provider-agnostic. Parallel. Production-ready.</p>
  <p align="center">
    <a href="https://github.com/aaxnet/CodeSwarm/actions/workflows/ci.yml"><img src="https://github.com/aaxnet/CodeSwarm/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
    <a href="https://github.com/aaxnet/CodeSwarm"><img src="https://img.shields.io/github/stars/aaxnet/CodeSwarm?style=social" alt="GitHub stars"></a>
    <a href="https://github.com/aaxnet/CodeSwarm"><img src="https://img.shields.io/github/forks/aaxnet/CodeSwarm?style=social" alt="GitHub forks"></a>
    <img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
    <img src="https://img.shields.io/badge/Node-20+-339933?logo=node.js&logoColor=white" alt="Node 20+">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
  </p>
</p>

<p align="center">
  <code>Issue #421 → Researcher → Coder ×3 → Tests → Reviewer → PR #438</code>
</p>

> [!IMPORTANT]
> **Give CodeSwarm a GitHub issue. It turns it into a tested and reviewed pull request.**
> Not *AI that writes code* — **AI engineering team** that ships production-ready PRs.

---

<p align="center">
  <img src="https://raw.githubusercontent.com/aaxnet/CodeSwarm/main/docs/demo.gif" alt="Demo: Issue to PR in 15 seconds" width="850" />
  <br><em>Issue created → Agents spawn → Code written → Tests pass → PR opened (add your 10–15s GIF to <code>docs/demo.gif</code>)</em>
</p>

---

## Table of Contents
- [Why CodeSwarm](#why-codeswarm)
- [How it Works](#how-it-works)
- [Features](#features)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
- [Architecture](#architecture)
- [MCP — Control via Claude / Cursor / OpenCode](#mcp)
- [Dashboard](#dashboard)
- [Configuration](#configuration)
- [Comparison](#comparison)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

## Why CodeSwarm

| Before | With CodeSwarm |
|---|---|
| 1 issue → hours of manual work | 1 issue → 5 AI agents → 1 ready-to-merge PR |
| AI pair-programming | **AI engineering team** — GitHub-native, autonomous, self-hosted |

> [!TIP]
> **Wow effect:** `1 GitHub Issue → 5 AI agents → parallel development → tests → review → CI fixes → 1 ready-to-merge PR`

## How it Works

```mermaid
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
```

<details>
<summary>Text version</summary>

```
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
```
</details>

## Features

|  |  |
|---|---|
| **Parallel worktrees** | Every agent works in isolated `git worktree` under `.codeswarm/task-xxx/` — no branch collisions. |
| **Conflict Resolver** | LLM-assisted 3-way merge. Detects `CONFLICT`, resolves, re-runs tests. |
| **Autonomous PR loop** | CI failure → parse logs → generate fix → push → re-run. Zero manual intervention. |
| **Provider-agnostic** | `LLMProvider` interface. OpenAI, Anthropic, OpenRouter, Google, Ollama, LiteLLM, any OpenAI-compatible + mock. |
| **Cost & safety guards** | `max_agents`, `max_cost_usd`, `timeout_minutes`, `max_depth`. Sandboxed `filesystem: repository_only`, `network: restricted`. |
| **Full audit trail** | Every `tool.called`, `file.changed`, `test.*`, `pr.*` stored in `agent_events` (SQLite now, Postgres in v0.3). |
| **Notifications** | Telegram + Dashboard + GitHub comments. |
| **MCP native** | Control swarm from Claude / Cursor / OpenCode via `swarm.*` tools. |

## Quick Start

### 1. Install

```bash
npx codeswarm init
```

Creates `codeswarm.yml` + `.env`. Fill `.env`:

```env
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
```

### 2. Run

**Docker (recommended)**

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

**Local**

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

### 3. Trigger

**Via label** — add `ai:ready` to any open issue (webhook auto-creates task).

**Via CLI — mock (no keys needed)**

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

**Via CLI — real**

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

> [!NOTE]
> `codeswarm issue run` first tries API (`http://localhost:3000`); if API is down, it falls back to local mock pipeline — great for demos and CI.

## CLI Reference

```bash
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
```

## Architecture

```
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)
```

**Repo layout**

```
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/
```

## MCP

Control the swarm from any MCP client:

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

| Tool | Description |
|---|---|
| `swarm.list_tasks()` | List tasks with status & progress |
| `swarm.run_task(issueNumber)` | Start swarm for an issue |
| `swarm.cancel_task(taskId)` | Cancel running task |
| `swarm.retry_task(taskId)` | Retry failed task |
| `swarm.spawn_agent(taskId, role)` | Spawn specific agent |
| `swarm.status()` | `activeAgents`, `queueLength`, `prsToday`, `successRate` |
| `swarm.review_pr(prNumber)` | Trigger reviewer |

## Dashboard

`http://localhost:3001` — live polling of `http://localhost:3000/api/status`

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

Terminal dashboard: `codeswarm status`

## Configuration

`codeswarm.yml` (see `codeswarm.yml.example`):

```yaml
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
```

Cost example: `gpt-4o-mini` ≈ $0.15/$0.6 per 1M tokens. A full pipeline ~$0.01–0.05 with mock, ~$0.2–0.6 with real models.

## Comparison

| Tool | Positioning |
|---|---|
| **OpenHands** | AI developer |
| **SWE-agent** | Issue → code fix |
| **Aider** | AI pair programming |
| **CodeSwarm** | **Orchestration of multiple AI developers** — GitHub-native, multi-agent, parallel, autonomous, self-hosted, provider-agnostic |

## Roadmap

> Full roadmap with timeline, Gantt, metrics and exit criteria → [**ROADMAP.md**](./ROADMAP.md)

```mermaid
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
```

| Version | Status | Target | Highlights |
| :--- | :---: | :--- | :--- |
| **v0.1** | ✅ Shipped | Sep 2026 | Issues → Planner/Coder/Tester/Reviewer → PR, worktrees, OpenAI/Anthropic, Docker, SQLite, CLI |
| **v0.2** | ✅ Shipped | Sep 2026 | Parallel coders ×5, Redis/BullMQ, CI fix loop, Telegram, MCP, Dashboard SSE, cost guards |
| **v0.3** | ✅ Shipped | Sep 2026 | Conflict auto-merge, Postgres, multi-repo, vector memory, custom agents, plugin system |
| **v1.0** | ✅ Shipped | Sep 2026 | GitHub App, org RBAC, self-hosted models, marketplace, gVisor sandbox, analytics |

<details>
<summary>v0.2 exit criteria</summary>

- 3 coders in parallel without file stomp
- 80% red CI auto-fixed, cost never exceeds `$2.00`, p95 < 8 min visible in Dashboard
</details>

<details>
<summary>v0.3 exit criteria</summary>

- >90% conflicts auto-merged, SQLite → Postgres via flag, 2 community agents contributed
</details>

> [!TIP]
> Want to shape the roadmap? React with 👍 on issues labeled `roadmap` or open a `roadmap/proposal`.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md). PRs welcome!

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

## License

[MIT](./LICENSE) © 2026 CodeSwarm