metaswarm

metaswarm is an open-source, MIT-licensed multi-agent orchestration framework built by Dave Sifry (founder of Technorati, Linuxcare, and Warmstart, and former tech executive at Lyft and Reddit). It coordinates 18 specialized AI agents through a structured 11-phase software development lifecycle — from GitHub issue to merged PR — with TDD enforcement, parallel design review gates, and a self-improving knowledge base. The project is hosted on GitHub and installable as a plugin for Claude Code, Gemini CLI, or Codex CLI.

What It Is

metaswarm is a prompt-driven orchestration layer that sits on top of AI coding assistants. Rather than relying on a single agent session to handle research, planning, implementation, testing, PR creation, and review, metaswarm breaks the work into phases and assigns each to a specialist agent persona. The system is described by its author as "an extraction of a production-tested agentic orchestration system" proven across hundreds of autonomous PRs in a production multi-tenant SaaS codebase. All agent definitions are markdown files — readable, editable, and extensible — with no custom runtime or server required beyond Claude Code and the optional BEADS CLI.

The 11-Phase Pipeline

Every feature runs through a structured sequence managed by an Issue Orchestrator:

• Research — A Researcher agent explores the codebase for patterns and dependencies
• Plan — An Architect agent creates an implementation plan
• Plan Validation — Three adversarial reviewers (Feasibility, Completeness, Scope & Alignment) must all approve
• Design Review Gate — Six specialist agents (PM, Architect, Designer, Security, UX Reviewer, CTO) review in parallel; all must approve within three iterations or the system escalates to a human
• Decompose — The plan is broken into work units with Definition of Done items and a dependency graph
• External Dependency Check — Identifies required API keys and prompts the user
• Orchestrated Execution — Each work unit runs through a 4-phase loop: Implement → Validate → Adversarial Review → Commit. Quality gates are blocking state transitions; there is no path from FAIL to COMMIT
• Final Review — Cross-unit integration check and full test suite
• PR Creation — Structured PR with description and test plan
• PR Shepherd — Monitors CI, handles review comments, resolves threads
• Close + Learn — Extracts learnings back into the JSONL knowledge base

Trust Nothing, Verify Everything

A core design principle is that the orchestrator never trusts subagent self-reports. When a coding agent reports "all tests pass," the orchestrator independently runs tsc, eslint, vitest, and coverage enforcement from .coverage-thresholds.json. Adversarial reviewers check each Definition of Done item with file:line evidence and return a binary PASS/FAIL. On failure, a fresh reviewer is spawned — never the same one — to avoid anchoring bias. Coverage enforcement is enforced at three levels: a Husky pre-push git hook, a GitHub Actions CI job, and an agent completion gate, all driven by a single config file.

Cross-Model Adversarial Review

metaswarm can delegate implementation and review tasks to OpenAI Codex CLI and Google Gemini CLI with one rule: the writer is always reviewed by a different model. If Claude writes the code, Codex or Gemini reviews it. Each external tool has a shell adapter with health checks and availability-aware escalation (Model A → Model B → Claude → user alert). Cross-model orchestration is opt-in and configured per-project via .metaswarm/external-tools.yaml.

Self-Improving Knowledge Base

After every merged PR, the self-reflect workflow analyzes what happened and writes structured JSONL entries covering patterns, gotchas, architectural decisions, and anti-patterns. The system also introspects Claude Code sessions for signals: repeated user corrections flag candidates for new skills, user disagreements capture preferred approaches, and repeated manual steps get flagged as workflow candidates. Agents use selective retrieval (bd prime) filtered by affected files, keywords, and work type — so the knowledge base can grow to thousands of entries without consuming context window.

Update: v0.12.0 — /handoff Command & First-Class Codex Plugin Support

The latest release, v0.12.0 (published June 2026), adds a /handoff command and first-class Codex CLI plugin support. The repository was created in February 2026 and has accumulated 370 stars and 52 forks as of its last update. The project is actively maintained, with the most recent push in June 2026. Installation is available via the Claude Code plugin marketplace, Gemini CLI extension system, Codex CLI plugin marketplace, or the cross-platform npx metaswarm init installer.