# Swarm Engine

> Multi-agent orchestration engine for AI coding tools

Swarm Engine coordinates multiple AI agents (Claude Code, OpenAI Codex, Google Gemini CLI) working together on code - researching, implementing, reviewing, testing - with an intelligent planner that learns from every run.

## Key Facts
- Open source, MIT licensed
- 26 specialized agents (16 core + 10 reviewers)
- 7 composable orchestration patterns (hybrid, TDD, red-team, spike, discover, review-cycle, research)
- Cost-based optimizer with adaptive replanning
- Heuristic learning from execution traces
- 871 tests across 54 files
- TypeScript, runs on Node.js 20+
- VS Code extension with @swarm Copilot Chat participant
- Cross-tool converter for Copilot, Cursor, Codex, Gemini, OpenCode, Windsurf

## Install
npm install -g swarm-engine
swarm install
swarm doctor

## Links
- Website: https://swarmengine.dev
- GitHub: https://github.com/simoncoombes/swarm-engine
- npm: https://www.npmjs.com/package/swarm-engine
- VS Code: https://marketplace.visualstudio.com/items?itemName=simoncoombes.swarm-engine

## Architecture

### Orchestration Engine
The core engine (src/runtime/engine.ts) executes tasks through a DAG-based phase scheduler. Each phase contains one or more agents that run in parallel. Phases execute sequentially, with output from earlier phases feeding into later ones.

### Agents
26 specialized agents, each defined as a markdown file with frontmatter (model, tools, backend):
- Core roles: researcher, implementer, reviewer, tester, debugger, refactorer, documenter, planner, orchestrator, integrator, judge, guardian, sentinel, grounding, librarian, devils-advocate
- Focused reviewers: security, performance, data-integrity, API-contracts, testing, accessibility, dependencies, error-handling, concurrency, documentation

### Patterns
Composable orchestration workflows:
- hybrid: Research > Implement > Review (default)
- tdd: Write tests > Implement > Verify > Review
- red-team: Build > Attack > Harden
- spike: Two approaches compete, judge picks winner
- discover: Hypothesize > Experiment > Build winner
- review-cycle: Implement > Challenge > Fix (iterative)
- research: Parallel fan-out investigation

Patterns can be composed: --pattern "tdd | red-team"

### Intelligent Planner
- Cost-Based Optimization: estimates token spend and duration before execution
- Adaptive Replanning: adjusts the plan mid-execution based on actual results
- Plan Search: generates 5 candidate plans, scores them, picks the best
- Heuristic Learning: extracts lessons from execution traces, applies to future plans
- Knowledge Compounding: organizes solutions by problem category for reuse
- Model Cascading: starts with cheaper models, escalates to expensive ones when needed

### Backends
Pluggable execution backends:
- Claude Code (default): uses claude CLI
- OpenAI Codex: uses codex CLI with JSONL streaming
- Google Gemini: uses gemini CLI
- Vercel AI SDK: programmatic access to 20+ LLM providers
- Mock: for testing

Different agents in the same orchestration can use different backends.

### Memory System
SQLite-backed with FTS5 full-text search:
- Heuristic store: lessons learned from past executions
- Trace store: full execution traces for analysis
- Knowledge compounder: structured solutions by problem category

### CLI Commands
- swarm orchestrate "task" - run a full orchestration
- swarm plan "task" - generate a plan without executing
- swarm run <agent> "task" - run a single agent
- swarm agents list - list available agents
- swarm template list/run/create - manage templates
- swarm memory search/store - query knowledge base
- swarm convert --to <tool> - export agents to other tools
- swarm doctor - check installation health
- swarm install - set up Claude Code integration
- swarm verify - run project verification commands
- swarm status - show running orchestrations
- swarm learn - interactive tutorial

### VS Code Extension
- @swarm participant in Copilot Chat
- Sidebar webview for orchestration status
- Command palette integration
- Status bar indicator

### Cross-Tool Export
The convert command translates agent definitions to:
- GitHub Copilot instructions
- Cursor rules
- OpenAI Codex agents
- Google Gemini CLI
- OpenCode
- Windsurf

### Templates
8 built-in parameterized templates:
- add-feature, add-endpoint, bug-fix, refactor, migration, security-audit, explore, fix-pr

## What Makes It Different
Unlike single-agent tools, Swarm Engine runs multiple agents in parallel through structured workflows (DAG-based phase execution). Unlike agent frameworks (LangGraph, CrewAI), it ships ready-to-use with 26 agents, 8 templates, and composable patterns. It learns from every run through heuristic extraction, execution traces, and knowledge compounding.

## Common Questions
Q: How is this different from Claude Code teams?
A: Claude Code teams provide the agent infrastructure. Swarm Engine adds composable patterns, cost optimization, adaptive replanning, learning from traces, and 26 specialized agents on top.

Q: Does it work with other tools besides Claude Code?
A: Yes. Backends for Codex CLI, Gemini CLI, and Vercel AI SDK (20+ providers). The convert command exports agents to 6 other tools.

Q: Is it free?
A: Yes, MIT licensed. You pay only for the LLM API tokens used by the agents.

Q: What models does it support?
A: Any model accessible through Claude Code, Codex CLI, Gemini CLI, or the Vercel AI SDK. This includes Claude (Opus, Sonnet, Haiku), GPT-4o, Gemini, Llama, Mistral, and more.

Q: Can I create custom agents?
A: Yes. Agents are markdown files with YAML frontmatter. Add them to the agents/ directory.

Q: Can I create custom patterns?
A: Yes. Define custom phase sequences in YAML templates or compose existing patterns inline.