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.
Badge for your README
Markdown
[](/listings/dsifry--metaswarm)HTML
<a href="/listings/dsifry--metaswarm"><img src="/api/listings/dsifry--metaswarm/badge.svg" alt="findsafeskills safety rating" /></a>Install
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
- {
- "name": "metaswarm",
- "version": "0.16.0",
- "description": "Multi-agent orchestration framework for Claude Code, Gemini CLI, and Codex CLI — 23 agents, 14 skills, 16 commands, quality gates, TDD enforcement",
- "author": {
- "name": "David Sifry",
- "email": "david@sifry.com"
- },
- "homepage": "https://github.com/dsifry/metaswarm",
- "repository": "https://github.com/dsifry/metaswarm",
- "license": "MIT",
- "keywords": ["orchestration", "agents", "tdd", "quality-gates", "beads"]
- }
README.md · README · 248 lines
- # metaswarm
- 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.
- ## What Is This?
- 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:
- - **23 agents: phase agents and specialized personas** (Researcher, Architect, Coder, Security Auditor, PR Shepherd, etc.)
- - **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
- - **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
- - **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
- - **Recursive orchestration**: Swarm Coordinators spawn Issue Orchestrators, which spawn sub-orchestrators for complex epics (swarm of swarms)
- - **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
- - **Knowledge base**: JSONL-based fact store for patterns, gotchas, decisions, and anti-patterns — agents prime from this before every task
- - **Quality rubrics**: Standardized review criteria for code, architecture, security, testing, planning, UX, release engineering, and adversarial spec compliance
- - **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
- - **Visual review**: Playwright-based screenshot capture for reviewing web UIs, presentations, and rendered pages
- - **PR lifecycle automation**: Autonomous CI monitoring, review comment handling, and thread resolution
- - **Workflow enforcement**: Mandatory quality gate intercepts at every handoff point — agents cannot skip design review, plan review, or knowledge capture
- - **Context recovery**: Approved plans and execution state persist to disk via BEADS, surviving context compaction and session interruption
- ## Architecture
- ```text
- Your prompt (spec with DoD items) or GitHub Issue
- │
- ▼
- ┌─────────────────────────────────┐
- │ Swarm Coordinator │
- │ - Assign to worktree │
- │ - Spawn Issue Orchestrator │
- └─────────────────────────────────┘
- │
- ▼
- ┌─────────────────────────────────┐
- │ Issue Orchestrator │
- │ - Create BEADS epic │
- │ - Decompose into work units │
- └─────────────────────────────────┘
- │
- ▼
- Research → Plan → Plan Review Gate (3 reviewers) → Design Review Gate (6 reviewers, on the plan)
- │
- ▼
- Work Unit Decomposition (DoD items, file scopes, dependency graph)
- │
- ▼
- Orchestrated Execution Loop (per work unit):
- IMPLEMENT → VALIDATE → ADVERSARIAL REVIEW → COMMIT
- (Optionally delegates IMPLEMENT to Codex/Gemini CLI)
- (Cross-model REVIEW: writer always reviewed by different model)
- │
- ▼
- Final Comprehensive Review (cross-unit integration)
- │
- ▼
- PR Creation → PR Shepherd (auto-monitors to merge)
- │
- ▼
- Closure → Knowledge Extraction (feedback loop)
- ```
- ## Repository Structure
- ```text
- metaswarm/
- ├── .claude-plugin/
- │ └── plugin.json # Claude Code plugin manifest
- ├── gemini-extension.json # Gemini CLI extension manifest
- ├── .codex/
- │ ├── install.sh # Codex CLI install script
- │ └── README.md # Codex CLI usage guide
- ├── hooks/
- │ ├── hooks.json # SessionStart + PreCompact hook definitions
- │ └── session-start.sh # Context priming (platform-aware)
- ├── skills/ # Orchestration skills (Agent Skills standard — portable)
- │ ├── start/ # Main entry point — workflow guide + 23 agent personas
- │ ├── orchestrated-execution/ # 4-phase execution loop (IMPLEMENT→VALIDATE→REVIEW→COMMIT)
- │ ├── design-review-gate/ # Parallel 6-agent review
- │ ├── plan-review-gate/ # 3-reviewer adversarial plan review
- │ ├── setup/ # Interactive project setup
- │ ├── migrate/ # Migration from npm to plugin installation
- │ ├── status/ # Diagnostic checks
- │ ├── pr-shepherd/ # PR lifecycle automation
- │ ├── handling-pr-comments/ # Review comment workflow
- │ ├── brainstorming-extension/
- │ ├── create-issue/
- │ ├── handoff/ # Session handoff doc for a fresh agent
- │ ├── external-tools/ # Cross-model AI delegation (Codex, Gemini CLI)
- │ └── visual-review/ # Playwright-based screenshot review
- ├── commands/ # Slash commands
- │ ├── *.md # Claude Code commands (16 files)
- │ └── metaswarm/*.toml # Gemini CLI commands (13 files)
- ├── agents/ # 23 agent definitions
- ├── rubrics/ # 10 quality review rubrics
- ├── guides/ # Development patterns
- ├── knowledge/ # Knowledge base schema + templates
- ├── templates/ # Setup templates (CLAUDE.md, AGENTS.md, GEMINI.md + append variants)
- ├── lib/ # Platform detection, sync, setup scripts
- ├── cli/ # Cross-platform installer (npx metaswarm)
- ├── CLAUDE.md # Claude Code project instructions
- ├── AGENTS.md # Codex CLI project instructions
- ├── GEMINI.md # Gemini CLI extension context
- ├── INSTALL.md
- ├── GETTING_STARTED.md
- ├── USAGE.md
- └── CONTRIBUTING.md
- ```
- ## Install
- ### Claude Code (recommended)
- ```bash
- claude plugin marketplace add dsifry/metaswarm-marketplace
- claude plugin install metaswarm
- ```
- Then run `/setup` in Claude Code.
- ### Gemini CLI
- ```bash
- gemini extensions install https://github.com/dsifry/metaswarm.git
- ```
- Then run `/metaswarm:setup` in your project.
- ### Codex CLI
- ```bash
- 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:
- ```bash
- npx metaswarm init
- ```
- ### Start building
- Run `/start-task` (Claude/Gemini) or `$start` (Codex) and describe what you want in plain English. No issue required.
- ```text
- /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.
- ## Per-phase models
- 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.
- | Role | Default model |
- |---|---|
- | `design-reviewer`, `plan-reviewer`, `adversarial-reviewer`, `planner` | opus |
- | `researcher`, `coder`, `pr-shepherd-agent`, `knowledge-curator-agent` | sonnet |
- | `issue-orchestrator`, `swarm-coordinator-agent` | inherit (your session model) |
- - **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`.
- - **Requires** Claude Code v2.1.251 or later.
- - **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).
- - Other hosts (Codex, Gemini, OpenCode, Cursor): see `skills/start/references/platform-adaptation.md`.
- ## Self-Learning System
- metaswarm doesn't just execute — it learns from every session and gets smarter over time.
- ### Automatic Reflection
- After every PR merge, the self-reflect workflow (`/self-reflect`) analyzes what happened:
- - **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
- - **Build and test failures** — Captures what broke and why, so agents avoid the same mistakes in future tasks
- - **Architectural decisions** — Records the rationale behind choices so future agents understand the "why", not just the "what"
- ### Conversation Introspection
- The reflection system also introspects into the Claude Code session itself, looking for:
- - **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.
- - **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.
- - **Friction points** — Repeated manual steps that could be codified into reusable workflows.
- These signals feed back into the knowledge base and can generate proposals for new skills, updated rubrics, or revised agent behaviors.
- ### Selective Knowledge Priming
- 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:
- ```text
- /prime authentication src/api/auth/ implementation
- ```
- See `commands/prime.md` for the exact filters.
- 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.
- ## Design Principles
- 1. **Knowledge-Driven Development** — Agents prime from the knowledge base before every task, reducing repeated mistakes
- 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
- 3. **Parallel Review Gates** — Independent specialist reviewers run concurrently, not sequentially
- 4. **Recursive Orchestration** — Orchestrators spawn sub-orchestrators for any level of complexity
- 5. **Agent Ownership** — Each agent owns its lifecycle; the orchestrator delegates, not micromanages
- 6. **BEADS as Source of Truth** — All task state lives in BEADS; agents coordinate via database, not messages
- 7. **Test-First Always** — TDD is mandatory, not optional. Coverage thresholds are enforced as a blocking gate before PR creation via `.coverage-thresholds.json`
- 8. **Git-Native Everything** — Issues, knowledge, specs all in version control
- 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
- ## Supported Platforms
- | Platform | Install Method | Commands |
- |---|---|---|
- | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Plugin marketplace | `/start-task`, `/setup`, etc. |
- | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Extension (`gemini extensions install`) | `/metaswarm:start-task`, etc. |
- | [Codex CLI](https://github.com/openai/codex) | Plugin marketplace | `$start`, `$setup`, etc. |
- ## Requirements
- - One of: Claude Code, Gemini CLI, or Codex CLI
- - Node.js 18+ (for automation scripts; contributing to metaswarm itself needs Node.js 22.8+ for the coverage gate)
- - [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`)
- - GitHub CLI (`gh`) — for PR automation (recommended)
- - Playwright — for visual review skill (optional, `npx playwright install chromium`)
- ## License
- MIT
- ## Acknowledgments
- metaswarm stands on the shoulders of two key projects:
- - **[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.
- - **[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.
- 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
- #!/usr/bin/env bash
- # .codex/install.sh
- # Install metaswarm skills for Codex CLI
- #
- # Usage:
- # 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
- # # or
- # bash .codex/install.sh (from cloned repo)
- set -euo pipefail
- INSTALL_DIR="${CODEX_HOME:-$HOME/.codex}/metaswarm"
- SKILLS_DIR="$HOME/.agents/skills"
- REPO_URL="https://github.com/dsifry/metaswarm.git"
- echo ""
- echo " metaswarm — Codex CLI installer"
- echo " ================================"
- echo ""
- # Check if already installed
- if [ -d "$INSTALL_DIR" ]; then
- echo " Updating existing installation at $INSTALL_DIR..."
- cd "$INSTALL_DIR"
- git pull --rebase origin main 2>/dev/null || {
- echo " Warning: git pull failed. Removing and re-cloning..."
- cd /
- rm -rf "$INSTALL_DIR"
- git clone "$REPO_URL" "$INSTALL_DIR"
- }
- else
- echo " Cloning metaswarm..."
- mkdir -p "$(dirname "$INSTALL_DIR")"
- git clone "$REPO_URL" "$INSTALL_DIR"
- fi
- # Symlink skills
- echo ""
- echo " Symlinking skills into $SKILLS_DIR..."
- mkdir -p "$SKILLS_DIR"
- linked=0
- for skill_dir in "$INSTALL_DIR/skills"/*/; do
- [ -d "$skill_dir" ] || continue
- skill_name="metaswarm-$(basename "$skill_dir")"
- target="$SKILLS_DIR/$skill_name"
- if [ -L "$target" ]; then
- # Update existing symlink
- rm "$target"
- elif [ -d "$target" ]; then
- echo " Warning: $target exists as a directory, skipping"
- continue
- fi
- ln -sf "$skill_dir" "$target"
- linked=$((linked + 1))
- done
- echo " Linked $linked skills."
- # Copy AGENTS.md template if project doesn't have one
- echo ""
- if [ -f "AGENTS.md" ] && grep -q "metaswarm" "AGENTS.md" 2>/dev/null; then
- echo " AGENTS.md already has metaswarm section."
- elif [ -f "AGENTS.md" ]; then
- echo " Note: AGENTS.md exists but doesn't reference metaswarm."
- echo " Run \$setup in your project to configure it."
- else
- echo " Note: No project-level AGENTS.md created."
- echo " Run \$setup in your project to set it up."
- fi
- echo ""
- echo " Done! metaswarm installed for Codex CLI."
- echo ""
- echo " Usage (Codex uses the 'name' field from SKILL.md frontmatter):"
- echo " \$start Begin tracked work"
- echo " \$setup Configure for your project"
- echo " \$brainstorming-extension Refine an idea"
- echo " \$design-review-gate Run 6-reviewer design review"
- echo ""
- echo " See .codex/README.md for the full skill list."
- 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 inFree to use. If it’s helped, pass it on.