Swarm
███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
Multi-agent coordination that survives context death.
Break big tasks into small ones. Spawn agents to work in parallel. Learn from what works.
swarmtools.ai · Documentation
Installation
OpenCode
npm install -g opencode-swarm-plugin
swarm setup
Done. Use /swarm "your task" in any OpenCode session.
Claude Code
Step 1: Install the CLI globally (required):
npm install -g opencode-swarm-plugin
Step 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.
What It Does
/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
Core Concepts
Hive
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" })
Hivemind
Semantic memory with embeddings. Store learnings, search later.
hivemind_store({ information: "Auth requires idempotency keys", tags: "auth,gotcha" })
hivemind_find({ query: "auth patterns" })
Swarm Mail
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: "..." })
Commands
| 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 |
CLI
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
How It Works
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 │
└────────────────┘
Architecture
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
Event Sourcing
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
Learning System
Every completion records duration, errors, files touched, success.