Skip to content
Back to search

metaswarm

Multi-agent orchestration framework for Claude Code, Gemini CLI, and Codex CLI — 23 agents, 14 skills, 16 commands, quality gates, TDD enforcement

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dsifry--metaswarm/badge.svg)](/listings/dsifry--metaswarm)

HTML

<a href="/listings/dsifry--metaswarm"><img src="/api/listings/dsifry--metaswarm/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code (recommended)

claude plugin marketplace add dsifry/metaswarm-marketplace
claude plugin install metaswarm

Then run `/setup` in Claude Code.

Gemini CLI

gemini extensions install https://github.com/dsifry/metaswarm.git

Then run `/metaswarm:setup` in your project.

Codex CLI

codex plugin marketplace add dsifry/metaswarm-marketplace
codex
# Open /plugins, select the metaswarm marketplace, and install metaswarm.

Then run `$setup` in your project.

Cross-platform installer

Detect installed CLIs and install metaswarm for all of them:

npx metaswarm init

Start building

Run `/start-task` (Claude/Gemini) or `$start` (Codex) and describe what you want in plain English. No issue required.

/start-task Add a webhook system with retry logic, signature verification,
and a delivery log UI.

See [INSTALL.md](INSTALL.md) for prerequisites, platform-specific details, and migration from older versions.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 13 lines
  1. {
  2. "name": "metaswarm",
  3. "version": "0.16.0",
  4. "description": "Multi-agent orchestration framework for Claude Code, Gemini CLI, and Codex CLI — 23 agents, 14 skills, 16 commands, quality gates, TDD enforcement",
  5. "author": {
  6. "name": "David Sifry",
  7. "email": "david@sifry.com"
  8. },
  9. "homepage": "https://github.com/dsifry/metaswarm",
  10. "repository": "https://github.com/dsifry/metaswarm",
  11. "license": "MIT",
  12. "keywords": ["orchestration", "agents", "tdd", "quality-gates", "beads"]
  13. }
README.md · README · 248 lines
  1. # metaswarm
  2. A self-improving multi-agent orchestration framework for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Gemini CLI, and Codex CLI. Coordinate 23 AI agents and 14 orchestration skills through a complete software development lifecycle, from issue to merged PR, with recursive orchestration, parallel review gates, and a git-native knowledge base.
  3. ## What Is This?
  4. metaswarm is an extraction of a production-tested agentic orchestration system. It has been proven in the field writing production-level code with 100% test coverage, mandatory TDD, multi-reviewed spec-driven development, and SDLC best practices across hundreds of PRs. It provides:
  5. - **23 agents: phase agents and specialized personas** (Researcher, Architect, Coder, Security Auditor, PR Shepherd, etc.)
  6. - **A structured 9-phase workflow**: Research → Plan (with its Plan Review Gate) → Design Review Gate → Work Unit Decomposition → Orchestrated Execution → Final Review → PR Creation → PR Shepherd → Closure & Learning
  7. - **4-Phase Orchestrated Execution Loop**: Each work unit runs through IMPLEMENT → VALIDATE → ADVERSARIAL REVIEW → COMMIT. The orchestrator validates independently (never trusts subagent self-reports), and adversarial reviewers check DoD compliance with file:line evidence
  8. - **Parallel Design Review Gate**: 6 specialist agents (PM, Architect, Designer, Security, UX Reviewer, CTO) review in parallel; severity-gated iteration (only `blocker: yes` findings re-run the gate, cap 10 rounds) before human escalation
  9. - **Recursive orchestration**: Swarm Coordinators spawn Issue Orchestrators, which spawn sub-orchestrators for complex epics (swarm of swarms)
  10. - **Git-native task tracking**: Uses [BEADS](https://github.com/steveyegge/beads) (`bd` CLI) for issue/task management and dependencies; metaswarm's own `/prime` command handles knowledge priming
  11. - **Knowledge base**: JSONL-based fact store for patterns, gotchas, decisions, and anti-patterns — agents prime from this before every task
  12. - **Quality rubrics**: Standardized review criteria for code, architecture, security, testing, planning, UX, release engineering, and adversarial spec compliance
  13. - **External AI tool delegation**: Optionally delegate implementation and review tasks to OpenAI Codex CLI and Google Gemini CLI for cost savings and cross-model adversarial review
  14. - **Visual review**: Playwright-based screenshot capture for reviewing web UIs, presentations, and rendered pages
  15. - **PR lifecycle automation**: Autonomous CI monitoring, review comment handling, and thread resolution
  16. - **Workflow enforcement**: Mandatory quality gate intercepts at every handoff point — agents cannot skip design review, plan review, or knowledge capture
  17. - **Context recovery**: Approved plans and execution state persist to disk via BEADS, surviving context compaction and session interruption
  18. ## Architecture
  19. ```text
  20. Your prompt (spec with DoD items) or GitHub Issue
  21. │
  22. ▼
  23. ┌─────────────────────────────────┐
  24. │ Swarm Coordinator │
  25. │ - Assign to worktree │
  26. │ - Spawn Issue Orchestrator │
  27. └─────────────────────────────────┘
  28. │
  29. ▼
  30. ┌─────────────────────────────────┐
  31. │ Issue Orchestrator │
  32. │ - Create BEADS epic │
  33. │ - Decompose into work units │
  34. └─────────────────────────────────┘
  35. │
  36. ▼
  37. Research → Plan → Plan Review Gate (3 reviewers) → Design Review Gate (6 reviewers, on the plan)
  38. │
  39. ▼
  40. Work Unit Decomposition (DoD items, file scopes, dependency graph)
  41. │
  42. ▼
  43. Orchestrated Execution Loop (per work unit):
  44. IMPLEMENT → VALIDATE → ADVERSARIAL REVIEW → COMMIT
  45. (Optionally delegates IMPLEMENT to Codex/Gemini CLI)
  46. (Cross-model REVIEW: writer always reviewed by different model)
  47. │
  48. ▼
  49. Final Comprehensive Review (cross-unit integration)
  50. │
  51. ▼
  52. PR Creation → PR Shepherd (auto-monitors to merge)
  53. │
  54. ▼
  55. Closure → Knowledge Extraction (feedback loop)
  56. ```
  57. ## Repository Structure
  58. ```text
  59. metaswarm/
  60. ├── .claude-plugin/
  61. │ └── plugin.json # Claude Code plugin manifest
  62. ├── gemini-extension.json # Gemini CLI extension manifest
  63. ├── .codex/
  64. │ ├── install.sh # Codex CLI install script
  65. │ └── README.md # Codex CLI usage guide
  66. ├── hooks/
  67. │ ├── hooks.json # SessionStart + PreCompact hook definitions
  68. │ └── session-start.sh # Context priming (platform-aware)
  69. ├── skills/ # Orchestration skills (Agent Skills standard — portable)
  70. │ ├── start/ # Main entry point — workflow guide + 23 agent personas
  71. │ ├── orchestrated-execution/ # 4-phase execution loop (IMPLEMENT→VALIDATE→REVIEW→COMMIT)
  72. │ ├── design-review-gate/ # Parallel 6-agent review
  73. │ ├── plan-review-gate/ # 3-reviewer adversarial plan review
  74. │ ├── setup/ # Interactive project setup
  75. │ ├── migrate/ # Migration from npm to plugin installation
  76. │ ├── status/ # Diagnostic checks
  77. │ ├── pr-shepherd/ # PR lifecycle automation
  78. │ ├── handling-pr-comments/ # Review comment workflow
  79. │ ├── brainstorming-extension/
  80. │ ├── create-issue/
  81. │ ├── handoff/ # Session handoff doc for a fresh agent
  82. │ ├── external-tools/ # Cross-model AI delegation (Codex, Gemini CLI)
  83. │ └── visual-review/ # Playwright-based screenshot review
  84. ├── commands/ # Slash commands
  85. │ ├── *.md # Claude Code commands (16 files)
  86. │ └── metaswarm/*.toml # Gemini CLI commands (13 files)
  87. ├── agents/ # 23 agent definitions
  88. ├── rubrics/ # 10 quality review rubrics
  89. ├── guides/ # Development patterns
  90. ├── knowledge/ # Knowledge base schema + templates
  91. ├── templates/ # Setup templates (CLAUDE.md, AGENTS.md, GEMINI.md + append variants)
  92. ├── lib/ # Platform detection, sync, setup scripts
  93. ├── cli/ # Cross-platform installer (npx metaswarm)
  94. ├── CLAUDE.md # Claude Code project instructions
  95. ├── AGENTS.md # Codex CLI project instructions
  96. ├── GEMINI.md # Gemini CLI extension context
  97. ├── INSTALL.md
  98. ├── GETTING_STARTED.md
  99. ├── USAGE.md
  100. └── CONTRIBUTING.md
  101. ```
  102. ## Install
  103. ### Claude Code (recommended)
  104. ```bash
  105. claude plugin marketplace add dsifry/metaswarm-marketplace
  106. claude plugin install metaswarm
  107. ```
  108. Then run `/setup` in Claude Code.
  109. ### Gemini CLI
  110. ```bash
  111. gemini extensions install https://github.com/dsifry/metaswarm.git
  112. ```
  113. Then run `/metaswarm:setup` in your project.
  114. ### Codex CLI
  115. ```bash
  116. codex plugin marketplace add dsifry/metaswarm-marketplace
  117. codex
  118. # Open /plugins, select the metaswarm marketplace, and install metaswarm.
  119. ```
  120. Then run `$setup` in your project.
  121. ### Cross-platform installer
  122. Detect installed CLIs and install metaswarm for all of them:
  123. ```bash
  124. npx metaswarm init
  125. ```
  126. ### Start building
  127. Run `/start-task` (Claude/Gemini) or `$start` (Codex) and describe what you want in plain English. No issue required.
  128. ```text
  129. /start-task Add a webhook system with retry logic, signature verification,
  130. and a delivery log UI.
  131. ```
  132. See [INSTALL.md](INSTALL.md) for prerequisites, platform-specific details, and migration from older versions.
  133. ## Per-phase models
  134. Each phase runs as its own agent type with a default model in its frontmatter, so reviewers get a strong model and mechanical work gets a cheaper one.
  135. | Role | Default model |
  136. |---|---|
  137. | `design-reviewer`, `plan-reviewer`, `adversarial-reviewer`, `planner` | opus |
  138. | `researcher`, `coder`, `pr-shepherd-agent`, `knowledge-curator-agent` | sonnet |
  139. | `issue-orchestrator`, `swarm-coordinator-agent` | inherit (your session model) |
  140. - **Override:** edit `.metaswarm/models.yaml`, then run `/update` to regenerate the `.claude/agents/metaswarm-<role>.md` files. Restart Claude Code after `.claude/agents/` is first created. `issue-orchestrator` and `swarm-coordinator-agent` are plugin-only (they inherit the session model) and are not configurable in `models.yaml`.
  141. - **Requires** Claude Code v2.1.251 or later.
  142. - **See what ran on which model:** `metaswarm-usage` (in the plugin's `bin/`, on PATH inside Claude Code — type `! metaswarm-usage` at the prompt) reports subagent cost and review-gate rounds from your Claude Code transcripts (`--json` for machine output).
  143. - Other hosts (Codex, Gemini, OpenCode, Cursor): see `skills/start/references/platform-adaptation.md`.
  144. ## Self-Learning System
  145. metaswarm doesn't just execute — it learns from every session and gets smarter over time.
  146. ### Automatic Reflection
  147. After every PR merge, the self-reflect workflow (`/self-reflect`) analyzes what happened:
  148. - **Code review feedback** — Extracts patterns, gotchas, and anti-patterns from reviewer comments (both human and automated) and writes them back to the knowledge base as structured JSONL entries
  149. - **Build and test failures** — Captures what broke and why, so agents avoid the same mistakes in future tasks
  150. - **Architectural decisions** — Records the rationale behind choices so future agents understand the "why", not just the "what"
  151. ### Conversation Introspection
  152. The reflection system also introspects into the Claude Code session itself, looking for:
  153. - **User repetition** — When a user corrects the same behavior multiple times or repeats instructions, this signals an opportunity for a new skill or command. The system flags these as candidates for automation.
  154. - **User disagreements** — When a user rejects or overrides Claude's recommendation, the system captures the user's preferred approach as a knowledge base entry, so agents align with the user's intent in future sessions.
  155. - **Friction points** — Repeated manual steps that could be codified into reusable workflows.
  156. These signals feed back into the knowledge base and can generate proposals for new skills, updated rubrics, or revised agent behaviors.
  157. ### Selective Knowledge Priming
  158. The knowledge base grows continuously, but agents don't load all of it. metaswarm's `/prime` command filters the knowledge base with `jq` (keyword over each fact and its tags, file over its affected files, work type over its fact type) so only the relevant subset is loaded:
  159. ```text
  160. /prime authentication src/api/auth/ implementation
  161. ```
  162. See `commands/prime.md` for the exact filters.
  163. This means the knowledge base can grow to hundreds or thousands of entries without consuming context window. Agents get precisely the facts they need — the 5 critical gotchas for the files they're about to touch, not the entire institutional memory.
  164. ## Design Principles
  165. 1. **Knowledge-Driven Development** — Agents prime from the knowledge base before every task, reducing repeated mistakes
  166. 2. **Trust Nothing, Verify Everything** — Orchestrators validate independently (run tests themselves, never trust subagent self-reports), review adversarially against written spec contracts, and optionally use cross-model review via external AI tools
  167. 3. **Parallel Review Gates** — Independent specialist reviewers run concurrently, not sequentially
  168. 4. **Recursive Orchestration** — Orchestrators spawn sub-orchestrators for any level of complexity
  169. 5. **Agent Ownership** — Each agent owns its lifecycle; the orchestrator delegates, not micromanages
  170. 6. **BEADS as Source of Truth** — All task state lives in BEADS; agents coordinate via database, not messages
  171. 7. **Test-First Always** — TDD is mandatory, not optional. Coverage thresholds are enforced as a blocking gate before PR creation via `.coverage-thresholds.json`
  172. 8. **Git-Native Everything** — Issues, knowledge, specs all in version control
  173. 9. **Human-in-the-Loop** — Proactive checkpoints at planned review points, plus automatic escalation or a Clarify stop when the severity rule says so (a recurring or disputed blocker, the 10-round cap, or a signal that the user is needed) or on ambiguous decisions
  174. ## Supported Platforms
  175. | Platform | Install Method | Commands |
  176. |---|---|---|
  177. | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Plugin marketplace | `/start-task`, `/setup`, etc. |
  178. | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Extension (`gemini extensions install`) | `/metaswarm:start-task`, etc. |
  179. | [Codex CLI](https://github.com/openai/codex) | Plugin marketplace | `$start`, `$setup`, etc. |
  180. ## Requirements
  181. - One of: Claude Code, Gemini CLI, or Codex CLI
  182. - Node.js 18+ (for automation scripts; contributing to metaswarm itself needs Node.js 22.8+ for the coverage gate)
  183. - [BEADS](https://github.com/steveyegge/beads) CLI (`bd`) — for task tracking (recommended). Minimum versions: bd ≥ 1.0.4 (tested with 1.3.4); the beads plugin version matching your bd; Dolt ≥ 2.4.0 only for server mode (`bd init --server`)
  184. - GitHub CLI (`gh`) — for PR automation (recommended)
  185. - Playwright — for visual review skill (optional, `npx playwright install chromium`)
  186. ## License
  187. MIT
  188. ## Acknowledgments
  189. metaswarm stands on the shoulders of two key projects:
  190. - **[BEADS](https://github.com/steveyegge/beads)** by [Steve Yegge](https://github.com/steveyegge) — The git-native, AI-first issue tracking system that serves as the coordination backbone for all agent task management and dependency tracking in metaswarm. BEADS made it possible to treat issue tracking as a first-class part of the codebase rather than an external service.
  191. - **[Superpowers](https://github.com/obra/superpowers)** by [Jesse Vincent](https://github.com/obra) and contributors — The agentic skills framework and software development methodology that provides foundational skills metaswarm builds on, including brainstorming, test-driven development, systematic debugging, and plan writing. Superpowers demonstrated that disciplined agent workflows aren't overhead — they're what make autonomous development reliable.
  192. metaswarm was created by [Dave Sifry](https://linkedin.com/in/dsifry), founder of Technorati, Linuxcare, and Warmstart, and former tech executive at Lyft and Reddit. Extracted from a production multi-tenant SaaS codebase where it has been writing production-level code with 100% test coverage, TDD, and spec-driven development across hundreds of autonomous PRs.
.codex/install.sh · Bundled script · 84 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # .codex/install.sh
  3. # Install metaswarm skills for Codex CLI
  4. #
  5. # Usage:
  6. # curl -sSL https://raw.githubusercontent.com/dsifry/metaswarm/main/.codex/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 6 on GitHub
  7. # # or
  8. # bash .codex/install.sh (from cloned repo)
  9. set -euo pipefail
  10. INSTALL_DIR="${CODEX_HOME:-$HOME/.codex}/metaswarm"
  11. SKILLS_DIR="$HOME/.agents/skills"
  12. REPO_URL="https://github.com/dsifry/metaswarm.git"
  13. echo ""
  14. echo " metaswarm — Codex CLI installer"
  15. echo " ================================"
  16. echo ""
  17. # Check if already installed
  18. if [ -d "$INSTALL_DIR" ]; then
  19. echo " Updating existing installation at $INSTALL_DIR..."
  20. cd "$INSTALL_DIR"
  21. git pull --rebase origin main 2>/dev/null || {
  22. echo " Warning: git pull failed. Removing and re-cloning..."
  23. cd /
  24. rm -rf "$INSTALL_DIR"
  25. git clone "$REPO_URL" "$INSTALL_DIR"
  26. }
  27. else
  28. echo " Cloning metaswarm..."
  29. mkdir -p "$(dirname "$INSTALL_DIR")"
  30. git clone "$REPO_URL" "$INSTALL_DIR"
  31. fi
  32. # Symlink skills
  33. echo ""
  34. echo " Symlinking skills into $SKILLS_DIR..."
  35. mkdir -p "$SKILLS_DIR"
  36. linked=0
  37. for skill_dir in "$INSTALL_DIR/skills"/*/; do
  38. [ -d "$skill_dir" ] || continue
  39. skill_name="metaswarm-$(basename "$skill_dir")"
  40. target="$SKILLS_DIR/$skill_name"
  41. if [ -L "$target" ]; then
  42. # Update existing symlink
  43. rm "$target"
  44. elif [ -d "$target" ]; then
  45. echo " Warning: $target exists as a directory, skipping"
  46. continue
  47. fi
  48. ln -sf "$skill_dir" "$target"
  49. linked=$((linked + 1))
  50. done
  51. echo " Linked $linked skills."
  52. # Copy AGENTS.md template if project doesn't have one
  53. echo ""
  54. if [ -f "AGENTS.md" ] && grep -q "metaswarm" "AGENTS.md" 2>/dev/null; then
  55. echo " AGENTS.md already has metaswarm section."
  56. elif [ -f "AGENTS.md" ]; then
  57. echo " Note: AGENTS.md exists but doesn't reference metaswarm."
  58. echo " Run \$setup in your project to configure it."
  59. else
  60. echo " Note: No project-level AGENTS.md created."
  61. echo " Run \$setup in your project to set it up."
  62. fi
  63. echo ""
  64. echo " Done! metaswarm installed for Codex CLI."
  65. echo ""
  66. echo " Usage (Codex uses the 'name' field from SKILL.md frontmatter):"
  67. echo " \$start Begin tracked work"
  68. echo " \$setup Configure for your project"
  69. echo " \$brainstorming-extension Refine an idea"
  70. echo " \$design-review-gate Run 6-reviewer design review"
  71. echo ""
  72. echo " See .codex/README.md for the full skill list."
  73. echo ""

Version history

  • v0.16.011/12/2026

  • v0.15.011/11/2026

  • v0.14.011/9/2026

  • v0.13.011/7/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.