Agent orchestration for Claude Code
swarmdo turns Claude Code into a coordinated multi-agent system — 60+ agent roles, hive-mind consensus, persistent vector memory, and a Postgres vector extension. Fully self-contained: every engine ships in the repo. Based on the original ruflo.
A real swarmdo pipeline: five named agents, coordinated over messages, sharing one memory.
What it does
swarmdo registers as an MCP server and wires agents, memory, and consensus into every session — with hooks that learn from what worked.
Hierarchical, mesh, ring, star, or hybrid topologies with anti-drift defaults. Named agents coordinate over real-time messages — pipelines, fan-out, supervisor patterns.
Queen-led coordination with raft, byzantine, gossip, CRDT, or quorum strategies. Byzantine mode tolerates f < n/3 faulty agents.
AgentDB-backed persistent memory with HNSW indexing — semantic search across sessions, namespaces shared by every agent in the swarm.
A pgvector-compatible extension with 230+ SQL functions, SIMD, and quantization. CREATE EXTENSION swarmvector — verified on PostgreSQL 16.
27 lifecycle hooks and 12 background workers record what succeeded, train routing patterns, and preload context before you ask.
Why use many token when few token do trick. /sdo-caveman-compress rewrites memory files into few-token caveman-speak — substance, code, and URLs preserved, backup kept. Vendored from the 82k-star original (MIT).
The laziest senior dev in the room, on demand. /sdo-ponytail forces the simplest solution that works: YAGNI, stdlib before dependencies, one line before fifty. Three intensities + audit and review lenses (MIT).
Eleven segments, three presets, one checklist. Run /sDo:statusline inside Claude Code and tick exactly what you want to see.
Every swarmdo slash command groups under /sDo: (skills /sdo-). Type /sDo in Claude Code and the whole toolkit surfaces together — legacy unprefixed copies auto-migrate on init.
Operator tools
The v1.3–v1.5 train added a day-to-day operations layer around the swarm — spend, safety, releases, model routing, and memory portability. No plugins required.
swarmdo usage reads your local Claude Code transcripts: daily/monthly/model/project views, live 5-hour block burn, tool-failure analytics, prompt-cache efficiency with dollars saved, and period-over-period diffs with per-model movers.
usage guard --block-usd 5 --strict turns limits for the active 5h block, today, or the month into ok/warn/over — exit 1 when over, safe for CI gates and Stop hooks.
swarmdo hud --watch is one screen for the whole install: block burn, task readiness, daemon workers, memory snapshots.
swarmdo repair runs a bounded, budget-capped headless claude loop that edits source until a failing test passes. Dry-run unless you --confirm.
swarmdo wt gives parallel agents their own git worktrees — add, list, diff, merge, remove — so concurrent edits never collide.
swarmdo changelog --out NOTES.md groups your conventional commits into linked release notes, ready for gh release create.
swarmdo hooks recipe notify-done --apply installs “ping me when Claude finishes” as a real Stop hook — idempotent, dry-run by default, never clobbers your settings. Desktop toasts via hooks notify -d.
memory export -f obsidian renders the vector DB as a markdown vault — frontmatter, live [[wikilinks]] — edit in Obsidian, then memory import -f obsidian syncs it back, re-embedded — add --watch and it stays live-synced while you type.
init --preset basic — five named tiers from minimal to max instead of dozens of flags. swarmdo preset info explains every rung.
Declare tier-mapped OpenRouter models in swarmdo.config.json and swarms pick per task — the router Thompson-samples among your candidates and dispatches the winner. config lint validates the section with the same parser the runtime uses.
swarmdo integrations wires swarmdo into Codex CLI, GitHub Copilot CLI, and pi — AGENTS.md plus each CLI’s MCP config, idempotent merges, and your Claude Code setup is never touched.
swarmdo tx export turns any Claude Code session into clean shareable markdown; tx search full-text-searches every session you’ve ever run.
Tasks carry real dependencies: task ready lists unblocked work, task graph renders the graph, and task parse-prd spec.md decomposes a spec straight into the DAG.
swarmdo testreport parses JUnit/TAP results into the exact failing tests + file:line + assertion message — the front-half of the test→fix loop, feeding straight into repair. Reads a file, dir, or stdin; --ci gates a build. Also an MCP tool.
swarmdo cycles scans the import graph for circular dependencies — the mutually-importing modules that cause temporal-dead-zone and undefined-export bugs (madge --circular style). Provably correct via Tarjan SCC; --ci gates a build. Also an MCP tool.
swarmdo affected walks the import graph from your git diff to list every file — and the minimal set of test files — a change could break, so you run only the tests your change touches (nx/turbo/jest --findRelatedTests style). Pipeable; also an MCP tool.
swarmdo hotspots ranks files by change-risk mined from git history — churn × recency × author-spread — so you (or an agent) can find the technical debt worth refactoring or testing, from data instead of a guess. Pairs with codegraph; also an MCP tool.
swarmdo apply is a forgiving git apply — it lands an agent’s unified diff even when the context lines have drifted, and reports exactly which hunks it couldn’t place instead of rejecting the whole patch. Also an MCP tool.
swarmdo sbom emits a CycloneDX or SPDX bill-of-materials from your lockfile — every dependency with version, package-url, license, and integrity hash, for compliance and vuln tooling. Deterministic (no timestamp), so it diffs cleanly in CI.
swarmdo license walks node_modules, resolves each dependency's SPDX license, and gates on an allow/deny policy — so a GPL or unknown license can't slip into a permissive tree. --ci fails the build; also an MCP tool. Deterministic.
swarmdo env scans your code for env-var references and reconciles them against .env / .env.example — flagging vars that are missing, unused, or undocumented before a deploy breaks. --ci fails the build; also an MCP tool. Deterministic.
swarmdo pack bundles a repo into one AI-friendly blob — markdown, XML, JSON, or plain, with a directory tree, per-file token counts, .gitignore-aware walking, and glob include/exclude. --tokens for a budget breakdown, --redact to strip secrets first. Deterministic.
swarmdo redact masks API keys, tokens, and private keys before they reach an LLM, a log, or memory — a gitleaks-style rule catalog plus an entropy fallback, as a stdin filter, a command wrapper, or a --scan CI gate. Deterministic, zero tokens; also exposed as MCP tools so agents self-censor.
swarmdo codegraph index maps every exported symbol in your TS/JS (1,750 across 289 files in under a second), then codegraph query buildIndex or codegraph file src/index.ts answers “where is this defined / what does this file export” from disk — no grep+read round-trips. It also maps the import graph, so codegraph importers answers “what breaks if I change this file.” Exposed as MCP tools too, so agents query it in-session.
npm test 2>&1 | swarmdo compact strips ANSI, collapses repeated lines, folds node_modules stack frames, and windows long logs — noisy command output shrinks before it burns an agent’s context. Deterministic, zero tokens; -- npm test to wrap a command (exit code propagates).
swarmdo mcp doctor statically validates every configured MCP server across .mcp.json and ~/.claude.json — missing binaries, bad URLs, malformed entries — without spawning anything.
Honest numbers
Benchmarks live in the repo and every claim is labeled. No mystery multipliers.
Efficiency
Two of the most-loved Claude Code skills ship inside swarmdo as first-class features — vendored MIT forks, integrated into the CLI, the agents, and the init wizard. Toggle them per project with swarmdo efficiency on|off.
Memory files (CLAUDE.md, notes, todos) get re-read every session — and they're written for humans, not token budgets. /sdo-caveman-compress rewrites them in few-token caveman-speak: substance, code, and URLs preserved, original backed up.
Also a CLI command — works outside Claude Code entirely:swarmdo compress CLAUDE.md · --check for a token-free dry run.
The laziest senior dev in the room, on demand. /sdo-ponytail applies one lens to everything: the best code is the code never written.
Three intensities (lite · full · ultra) plus audit, review, and debt lenses. And it reaches the swarm too: pass ponytail: true when spawning an agent — or set SWARMDO_PONYTAIL=1 — and every spawned agent inherits the persona.
Explicit ponytail: false always wins over the env. Skills are user-invoked: on means available, never automatic.
Vendored with attribution from the MIT originals: caveman by Julius Brussee and ponytail by Dietrich Gebert — see NOTICE.
Self-contained
No runtime downloads from third-party registries, no surprise upstream churn. Each engine is vendored, renamed, smoke-tested, and file-linked.
| Engine | What it is | Form |
|---|---|---|
| swarmvector | Vector database — HNSW, ONNX embeddings (384-dim), Graph RAG | native + wasm |
| swarmvector-postgres | Postgres extension, pgvector drop-in, pg 14–17 | pgrx crate |
| swarmllm | Local model layer — MicroLoRA adapters, SONA learning | native + wasm |
| swarmdo-swarm | Swarm MCP server — cognitive patterns, neural agents | node + wasm |
| agentdb | Agent memory store — vectors, reinforcement learning | vendored |
| agentic-flow | Agent runtime integration and ONNX embedding backend | vendored |
| @swarmnet/bmssp | Graph pathfinding for agent topology routing | wasm |
Install
Scaffolds .claude/ with agents, skills, hooks, and the /sDo:statusline command.
Registers the MCP server — 200+ tools for agents, memory, and coordination.
Claude Code spawns the agents; swarmdo coordinates, remembers, and learns.
FAQ
swarmdo turns Claude Code into a coordinated multi-agent system. One prompt spawns a swarm of named agents — researcher, architect, coder, tester, reviewer — that coordinate over messages, share persistent vector memory, and learn from what worked.
Yes — it’s built for it. swarmdo registers as an MCP server (200+ tools), ships agents and skills into .claude/, and adds slash commands like /sDo:statusline. Codex runs alongside through the dual-mode package.
MIT licensed, based on the original popular ruflo — attribution preserved in LICENSE and NOTICE. Every engine is vendored in the repo; nothing phones home.
The vector engine family: an embedded vector database with HNSW indexing and ONNX embeddings, plus a pgvector-compatible Postgres extension — CREATE EXTENSION swarmvector — with 230+ SQL functions, verified on PostgreSQL 16.
npx swarmdo init --wizard, then claude mcp add swarmdo -- npx -y @swarmdo/cli@latest. Ask Claude Code to “use a swarm” and swarmdo does the coordinating.