███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
Multi-agent coordination that survives context death.
Break big tasks into small ones. Spawn agents to work in parallel. Learn from what works.
npm install -g opencode-swarm-plugin
swarm setupDone. Use /swarm "your task" in any OpenCode session.
Step 1: Install the CLI globally (required):
npm install -g opencode-swarm-pluginStep 2: Add the marketplace in Claude Code:
/plugin
→ Manage marketplaces
→ Add marketplace
→ Enter: joelhooks/swarm-tools
Step 3: Install the plugin:
/plugin
→ Manage plugins
→ swarm-tools
→ swarm
→ Install
The MCP server starts automatically. Use /swarm "your task" in any session.
/swarm "Add user authentication with OAuth"
- Decomposes the task into parallelizable subtasks
- Creates cells in the Hive (git-backed task tracker)
- Spawns workers with file reservations (no conflicts)
- Coordinates via Swarm Mail (embedded event store)
- Reviews each completion before approval
- Learns what worked for next time
Git-backed task tracking in .hive/. Survives sessions, syncs via git.
hive_create({ title: "Fix auth bug", type: "bug" })
hive_cells({ status: "in_progress" })
hive_close({ id: "cell-123", reason: "Fixed" })
Semantic memory with embeddings. Store learnings, search later.
hivemind_store({ information: "Auth requires idempotency keys", tags: "auth,gotcha" })
hivemind_find({ query: "auth patterns" })
Actor-model coordination between agents. File reservations, messaging, checkpoints.
swarmmail_reserve({ paths: ["src/auth/*"], exclusive: true })
swarmmail_send({ to: ["worker-b"], subject: "Need types", body: "..." })
| Command | Description |
|---|---|
/swarm <task> |
Decompose and spawn parallel workers |
/hive |
Query and manage tasks |
/inbox |
Check messages from other agents |
/status |
Swarm coordination status |
/handoff |
End session with sync and handoff notes |
swarm setup # Configure OpenCode/Claude Code integration
swarm doctor # Check dependencies (Ollama for embeddings)
swarm init # Initialize hive in current project
swarm config # Show config paths Your Task
│
▼
┌────────────────┐
│ COORDINATOR │
│ │
│ 1. Query past │
│ sessions │
│ 2. Pick strat │
│ 3. Decompose │
└────────────────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Worker A │ │ Worker B │ │ Worker C │
│ │ │ │ │ │
│ 🔒 files │───▶│ 🔒 files │ │ 🔒 files │
└────────────┘ └────────────┘ └────────────┘
│ │ │
└─────────────────┼─────────────────┘
▼
┌────────────────┐
│ LEARNING │
│ │
│ Record outcome │
│ Update weights │
└────────────────┘
Everything runs locally. No external servers.
- libSQL - Embedded SQLite for event sourcing
- Hive - Git-backed
.hive/directory for tasks - Hivemind - Semantic memory with Ollama embeddings (falls back to FTS)
- Swarm Mail - DurableMailbox, DurableLock, DurableDeferred primitives
All state is an append-only event log:
agent_registered → Agent joins swarm
message_sent → Agent-to-agent communication
file_reserved → Exclusive lock acquired
file_released → Lock released
checkpoint → Progress snapshot
outcome → Completion result
Every completion records duration, errors, files touched, success.
- Patterns mature: candidate → established → proven
- Anti-patterns auto-generate when failure rate > 60%
- Confidence decays over 90 days unless revalidated
| Required | Optional |
|---|---|
| Bun | Ollama - local embeddings |
Run swarm doctor to check status.
bun install
bun turbo build
bun turbo test- MCP Agent Mail - inspiration for multi-agent coordination
- Electric SQL - durable streams patterns
- Superpowers - verification patterns
MIT