swarm

Swarm — Claude Code Multi-Agent Plugin

Orchestrate parallel and sequential AI agent swarms from YAML blueprints, with a live web dashboard. Define who does what and in what order; Swarm handles the rest.

Features

• Topology graph — topology diagram renders live as agents run; nodes colour-code by status (pending / running / done / error)
• Live dashboard — SSE-powered log stream, per-agent token counts, and elapsed time at http://localhost:7700
• Blueprint library — ready-made blueprints for research, code review, security audit, content creation, and incident response
• Cost tracking — per-agent token accounting, per-run USD budget cap, and a Cost tab in the dashboard
• Conditional branching — group agents, evaluate agent output, and route execution down true/false branches (Phase 2)
• Compound conditions — combine gates with AND / OR / NOT and retry on fallback (Phase 2.2)
• Checkpoint & resume — interrupted runs can be continued from the last completed stage
• Run history — every run is archived; replay any past run in the dashboard History tab
• Zero dependencies — pure Node.js 18+, no npm, no package.json

Quick Start

/swarm research "compare top AI frameworks 2026"
/swarm code-review "PR #42 changes"
/swarm debug "TypeError in auth middleware"

The dashboard auto-starts at http://localhost:7700 showing a live topology graph, agent status, and colour-coded log stream.

Installation

Swarm is a Claude Code plugin (manifest at .claude-plugin/plugin.json). Install it the same way as any plugin — add the repo through a plugin marketplace, or clone it into a directory Claude Code discovers plugins from. The seven /swarm* slash commands in commands/ are auto-discovered on load.

No npm install needed — the runtime uses only Node.js built-ins (Node 18+).

Commands

Command	Description
/swarm <blueprint> "<task>"	Run a blueprint against a task
/swarm <blueprint> "<task>" --dry-run	Preview execution plan without running
/swarm list	List available blueprints
/swarm-init	Interactive wizard to build a blueprint step by step
/swarm-new "<description>"	Generate a new blueprint from a natural language description
/swarm-preview <blueprint>	Preview topology, plan, and validation before running
/swarm-history	Browse past swarm runs and open their outputs
/swarm-decompose "<goal>"	Break a large goal into an ordered sequence of swarm runs
/swarm-scaffold <blueprint>	Scaffold a new blueprint or validate an existing one

Blueprints

Blueprints live in swarms/*.yaml. Included examples:

Blueprint	Topology	What it does
research	parallel → pipeline	Searcher + analyst in parallel, synthesiser combines results
code-review	parallel → pipeline	Bug, perf, and security reviewers in parallel, summariser consolidates
debug	pipeline	Reproduce → diagnose → fix → verify in sequence
security-audit	parallel → pipeline	Vulnerability scan + dependency check, then remediation advice
content-pipeline	4-stage pipeline	Research → outline → write → edit
incident-response	parallel → conditional	Log + metric analysis, then escalate or resolve based on severity

Flow syntax

Flow string	Topology
"A, B → C"	A and B in parallel, then C
"A → B → C"	Sequential pipeline
"A, B, C"	All three in parallel
"A → B, C → D"	A, then B+C parallel, then D
"G → if cond: X else: Y"	Run group G, branch on condition (Phase 2)

Both → and -> are accepted. Comma = parallel within a stage. Arrow = next stage.

Blueprint reference

name: my-swarm               # required — alphanumeric + hyphens
version: "1.0.0"             # optional
description: What this does  # required
flow: "agent-a, agent-b → agent-c"  # required — topology string
output: markdown             # optional — markdown | json

limits:                      # optional — per-run resource caps
  agent_timeout: 300         # seconds per agent attempt
  agent_retries: 1           # retries after timeout or error
  max_cost_usd: 1.00         # USD budget; run aborts gracefully if exceeded
  max_tokens: 200000         # total token budget

agents:
  agent-a:
    role: Describe exactly what this agent does.
    tools: [WebSearch, WebFetch]   # optional Claude tool allowlist
  agent-b:
    role: Describe this agent's role.
  agent-c:
    role: Combine inputs from agent-a and agent-b into a final report.

Required fields: name, flow, agents. Every agent named in flow must have an entry in agents.

Phase 2 — groups and conditions

For conditional branching, add groups and conditions:

flow: "research → if quality_ok: synthesis else: fallback"