Your agents. Orchestrated.
Coordinate multiple AI agents working on your code - researching, implementing, reviewing, testing - with an intelligent planner that learns from every run.
Works with Claude Code, OpenAI Codex, and Google Gemini CLI. Mix models across agents in the same orchestration.
Swarm Engine - hybrid pattern
Phase 1: research ━━━━━━━━━━━━━━━━━━━━ 100% 42s
✓ researcher-code sonnet 3.2K tokens
✓ researcher-context sonnet 1.8K tokens
Phase 2: implement ━━━━━━━━━━━━━━━━━━━ 55% 1m 12s
● implementer opus src/auth/rate-limit.ts...
Phase 3: review pending
○ reviewer-correctness ○ reviewer-security ○ reviewer-convention
$0.24 spent | 12.8K tokens | ~2m remaining
┌─────────────────────────────────────────────────┐
│ ✓ Orchestration complete │
│ Pattern: hybrid (3 phases, 6 agents) │
│ Duration: 3m 42s | Tokens: 47K | Cost: $0.38 │
│ │
│ Save as template? deploy-lambda │
└─────────────────────────────────────────────────┘
npm (recommended):
npm install -g swarm-engine
swarm install # set up Claude Code integration (agents, commands, hooks)
swarm doctor # verify everything worksHomebrew:
brew tap simoncoombes/swarm
brew install swarm-engine
swarm installnpx (try without installing):
npx swarm-engine doctorFrom source:
git clone https://github.com/simoncoombes/swarm-engine.git ~/dev/swarm-engine
cd ~/dev/swarm-engine && npm install && npm run build && npm link
swarm installRequires Node.js 20+, jq, and at least one of Claude Code, Codex, or Gemini CLI.
# From Claude Code (agents run in split panes)
/swarm "add rate limiting to the API"
# From any terminal
swarm orchestrate "add rate limiting to the API"
# Preview what will happen before running
swarm plan "add rate limiting" --dry-runSwarm Engine ships with a VS Code extension that works in both VS Code and Cursor.
Install the extension:
cd ~/dev/swarm-engine/vscode-extension
npm install && npm run build
npx @vscode/vsce package --allow-missing-repositoryThen: Cmd+Shift+P > "Extensions: Install from VSIX" > select the .vsix file.
What you get:
@swarmin Copilot Chat - type@swarm add auth middlewareand it orchestrates the task- Sidebar panel with quick actions, pattern browser, and agent list
- Command palette (
Cmd+Shift+P> "Swarm") for all commands - Status bar shortcut
Copilot Chat examples:
@swarm add rate limiting to the API
@swarm plan add auth middleware
@swarm template bug-fix
@swarm status
AI coding agents work alone. You get one agent, one model, one approach. For complex tasks, that's not enough.
Swarm Engine orchestrates multiple agents in parallel. Each has a specialized role, the right model for the job, and shared knowledge from past runs.
- 7 composable patterns - hybrid, TDD, red-team, spike, discover, review-cycle, research. Compose them:
--pattern "research | tdd | red-team" - Intelligent planner - cost-based optimization, adaptive execution, learns from every run
- Mix any backend - Claude for implementation, Codex for review, Gemini for research. Different model per agent.
- Reusable templates - save successful workflows, run them again with different parameters
- 26 specialized agents - 16 core roles plus 10 focused reviewers (security, performance, data integrity, API contracts, testing, accessibility, dependencies, error handling, concurrency, documentation)
- 871 tests - 4 rounds of security review, clean on all adversarial attack vectors
Save successful orchestrations as reusable templates:
swarm template list
add-endpoint - REST API endpoint with tests
bug-fix - Reproduce, diagnose, fix, verify
security-audit - OWASP security review
refactor - Safe refactoring with verification gates
migration - Schema migration with rollback
swarm template run add-endpoint -iSee exactly what will happen before it runs:
swarm plan "add auth middleware" --pattern hybrid
Phase 1: research [parallel]
researcher-code sonnet ~5K tokens
researcher-context sonnet ~3K tokens
Phase 2: implement [sequential]
implementer opus ~15K tokens
Phase 3: review [parallel]
reviewer-correct opus ~8K tokens
reviewer-security opus ~8K tokens
Est. cost: $0.51 | Est. duration: 95s
Optimizations: model downgrade for research phase (sonnet vs opus)Daily use
| Command | What it does |
|---|---|
/swarm <task> |
Full orchestration - research, implement, review |
/review-cycle <task> |
Implement with iterative quality gate |
/diff-review [base] |
Review branch diff before PR |
/research <question> |
Parallel research across multiple angles |
/tdd <feature> |
Test-driven: write tests first, then implement |
Advanced
| Command | What it does |
|---|---|
/spike <problem> |
Two approaches compete, judge picks winner |
/red-team <task> |
Adversarial build and break |
/discover <problem> |
Hypothesize, experiment, implement winner |
/fix-pr <PR#> |
Fix PR review comments |
/resume |
Resume from checkpoint |
7 composable patterns. Use them individually or combine them.
| Pattern | Flow | Phases |
|---|---|---|
| hybrid | Research, Implement, Review | 3 |
| research | Parallel fan-out research | 1 |
| review-cycle | Implement, Challenge, Review (iterative) | 4 |
| tdd | Test-first, Implement, Verify, Review | 5 |
| spike | Two approaches compete, judge decides | 4 |
| red-team | Build, Break, Harden | 4 |
| discover | Hypothesize, Experiment, Implement winner | 5 |
Compose patterns: swarm orchestrate "task" --pattern "tdd | red-team"
16 core agents plus 10 specialized reviewers.
| Agent | Role |
|---|---|
| researcher | Explores code, finds patterns, traces dependencies |
| implementer | Writes clean, tested code following conventions |
| reviewer | Finds bugs, security issues, convention violations |
| tester | Writes and runs tests, reports coverage |
| debugger | Reproduces and fixes bugs systematically |
| planner | Designs architecture before code is written |
| refactorer | Safe incremental refactoring with test gates |
| integrator | Verifies cross-module contracts after parallel work |
| devils-advocate | Challenges every assumption before review |
| grounding | Verifies the implementation solves the actual problem |
| orchestrator | Coordinates everything |
| judge | Evaluates competing implementations and picks the winner |
| sentinel | Background: watches git activity |
| guardian | Background: runs affected tests |
| librarian | Background: maintains knowledge quality |
| documenter | Writes technical documentation |
Specialized reviewers: security, performance, data integrity, API contracts, testing, accessibility, dependencies, error handling, concurrency, documentation.
Convert your agents to work natively in other tools:
swarm convert --to copilot # GitHub Copilot .agent.md format
swarm convert --to cursor # Cursor .mdc rules
swarm convert --to codex # OpenAI Codex prompts
swarm convert --to gemini # Gemini CLI skills
swarm convert --to opencode # OpenCode agents
swarm convert --to windsurf # Windsurf skillsSQLite-backed knowledge base with full-text search. Syncs to Obsidian vault for cross-machine access. The engine learns from every run and compounds knowledge over time.
swarm memory search "authentication"
swarm compound stats- Node.js 20+
- jq (
brew install jq) - At least one AI backend:
- Claude Code (recommended)
- Codex CLI (
npm i -g @openai/codex) - Gemini CLI (
npm i -g @google/gemini-cli)
See CONTRIBUTING.md. Share agents, templates, patterns, and plugins.
Swarm Engine orchestrates AI coding tools that consume API tokens from third-party providers (Anthropic, OpenAI, Google, etc.). Each orchestration incurs costs billed directly to your accounts with those providers. You are solely responsible for monitoring and managing your API usage and costs.
Use the --budget flag to set cost caps, --dry-run to preview estimated costs before running, and swarm plan to inspect token estimates. The built-in cost tracking is an estimate and may not reflect exact provider billing.
Swarm Engine is not affiliated with Anthropic, OpenAI, or Google. Ensure your use of each provider's API complies with their respective terms of service.
MIT