Swarm
Multi-agent swarm coordination for OpenCode and Claude Code: break big tasks into parallel subtasks while persisting memory and learnings locally.
- Source repo
- joelhooks/swarm-tools
- Stars
- ★ 748
- Last updated
- 5mo ago
- Primary language
- TypeScript
- FA score
- 60/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An OpenCode developer who needs to split a large feature (e.g. OAuth user authentication) into subtasks executed simultaneously by multiple agents
- Not a fit if
- Teams not using OpenCode or Claude Code
- Environments where the Bun runtime cannot be installed
- Users wanting semantic memory without running Ollama locally
- Source review
- 60/100 · Some gaps
What does this agent do, and when should you use it?
Swarm (npm package opencode-swarm-plugin, repository joelhooks/swarm-tools) is a locally running multi-agent coordination system delivered as an OpenCode plugin and a Claude Code plugin/MCP server. It decomposes a given task into parallelizable subtasks, creates cells in the Hive git-backed task tracker (.hive/ directory), and assigns workers file reservation locks to prevent conflicts. Agents communicate through Swarm Mail, an embedded event store built on libSQL. Every completion records duration, errors, files touched, and success, feeding a learning system where patterns mature over time; anti-patterns auto-generate when failure rate exceeds 60%, and confidence decays after 90 days without revalidation. All state is an append-only event log, and every component (libSQL, Hive, Hivemind, Swarm Mail) runs locally with no external servers.
When you run /swarm "task", a coordinator queries past sessions via Hivemind, picks a strategy, and decomposes the work. It creates task cells in Hive (hive_create / hive_cells / hive_close), acquires exclusive file locks with swarmmail_reserve (e.g. src/auth/*), and sends messages between workers with swarmmail_send. Workers operate in parallel and each completion is reviewed before approval. Outcomes are logged as events (duration, errors, files, success), and patterns mature through candidate → established → proven stages. Hivemind provides semantic storage and retrieval with Ollama embeddings (hivemind_store / hivemind_find), falling back to full-text search without Ollama. The CLI offers swarm setup / doctor / init / config; slash commands include /swarm, /hive, /inbox, /status, and /handoff.
- An OpenCode developer who needs to split a large feature (e.g. OAuth user authentication) into subtasks executed simultaneously by multiple agents
- A Claude Code user who wants an MCP plugin so multiple workers can modify the same codebase without conflicts via file reservation locks
- A team that wants git-synced .hive/ task state to persist across sessions and produce handoff notes (/handoff)
- A developer building project memory, storing domain gotchas (e.g. auth idempotency keys) in Hivemind and retrieving them semantically in later tasks
- A user with data-sovereignty requirements who wants all coordination and memory infrastructure running locally (libSQL event store plus optional Ollama embeddings)
How do you install or deploy this agent?
Prerequisite: install Bun (required runtime). Optional: install Ollama for local embeddings.
OpenCode:
- npm install -g opencode-swarm-plugin
- swarm setup
- Use /swarm "your task" in any OpenCode session.
Claude Code:
- npm install -g opencode-swarm-plugin
- In Claude Code: /plugin → Manage marketplaces → Add marketplace, enter joelhooks/swarm-tools
- /plugin → Manage plugins → swarm-tools → swarm → Install
The MCP server starts automatically.
How do you use this agent?
- Run swarm init in your project root to initialize the Hive; use swarm doctor to check dependencies.
- In a session, run /swarm "Add user authentication with OAuth" to trigger decomposition and parallel worker spawning.
- Use /hive to query and manage tasks, /inbox to read messages from other agents, /status for coordination status, and /handoff to end a session with sync and handoff notes.
- Optionally configure embeddings: export OLLAMA_MODEL=nomic-embed-text (default mxbai-embed-large) and export OLLAMA_HOST=http://localhost:11434. Supported models: mxbai-embed-large (1024d), nomic-embed-text (768d), all-minilm (384d), snowflake-arctic-embed (1024d).
What are this agent's strengths and limitations?
- File reservation locks (swarmmail_reserve exclusive locks) mechanically prevent multi-worker edit conflicts on the same files — a capability most multi-agent setups lack
- Fully local: libSQL embedded SQLite, a git-backed .hive/ task directory, and optional local Ollama embeddings; no external servers
- Learning system has concrete mechanics: patterns mature through candidate→established→proven, anti-patterns auto-generate above 60% failure rate, and confidence decays over 90 days
- Full event sourcing (agent_registered, message_sent, file_reserved, checkpoint, outcome, etc.) makes all state auditable and replayable
- The repository lists no license, so commercial or enterprise-internal use requires verifying the terms first
- It depends on the Bun runtime and an OpenCode or Claude Code host; other coding environments require adaptation
- Semantic memory requires local Ollama; without it the system falls back to full-text search and loses semantic retrieval quality
- Coordinating parallel workers costs tokens and adds review overhead, which may not pay off for small tasks; the learning benefits are documented but not independently verified
How does this agent compare with similar options?
The README credits MCP Agent Mail (Dicklesworthstone/mcp_agent_mail) as the inspiration for its multi-agent coordination, and Electric SQL's durable streams patterns plus obra/superpowers' verification patterns; it provides no formal comparison against these or other alternatives.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Swarm This agent | 60 · Some gaps | Agent plugin / skillFree | ★ 748 | 5mo ago | TypeScript | Claude Code |
| Claudexor | 76 · Good | CLIFree + model costs | ★ 518 | today | TypeScript | Codex · Claude Code |
| Oh My OpenAgent | 49 · Major gaps | Agent plugin / skillFree + model costs | ★ 70k | today | TypeScript | Claude Code |
| Ouroboros Agent OS | 53 · Major gaps | CLIFree + model costs | ★ 6.3k | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Local-first architecture (libSQL, git-backed .hive/, Ollama local embeddings, no external servers) minimizes exfiltration; file reservations reduce conflicting permissions; swarm doctor checks dependencies. Deductions: coordinator spawns workers and writes files with no documented user confirmation for destructive steps; no sensitive-data handling or purge policy; rollback relies on git event sourcing/checkpoints without an explicit recovery procedure.
CI covers build, typecheck, tarball verification, targeted tests, evalite gates, and CodeQL scanning. Deductions: CI comments admit the full unit suite hangs in GitHub Actions, so only a subset runs — overall reliability verification is incomplete; Bun/Ollama are non-universal prerequisites.
README targets both OpenCode and Claude Code; swarm doctor adapts to environment; embeddings degrade to FTS. Deductions: capability boundaries (task size limits, worker counts, failure behavior) are barely documented.
Clear information architecture (Hive/Hivemind/Swarm Mail layers, event-sourcing list, command table); MIT declared in README; changesets versioning; credits given. Deductions: no LICENSE file or CHANGELOG visible in provided files; known limitations only implicit (full test suite hanging is not disclosed to users); maintenance responsibility and update path undocumented.
Decomposing large tasks into parallel workers with file reservations plus a learning system offers clear marginal value; outputs are structured (hive, mail, event log) and usable. Deduction: learning-system benefits (pattern maturation, 60% failure threshold) are asserted without evidence; cost/benefit cannot be verified statically.
README commands corroborate with CI-verified artifacts and test files; credits separate inspiration from own work; eval results emitted as traceable JSON. Deduction: static review cannot confirm actual learning/eval efficacy; confidence limited to low.
- The coordinator spawns workers and writes files automatically; validate in an isolated environment first and confirm whether destructive operations require human confirmation.
- The full unit suite hangs in CI and only a subset runs; treat reliability claims with discount.
- Verify the repository LICENSE file and npm package contents yourself; the MIT notice in the README is not independently confirmed here.
- Learning memory persists local session data; assess what .hive/ and embedding databases retain before using on sensitive projects.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Patch Changes - [f21f581](https://github.com/joelhooks/swarm-tools/commit/f21f581c2efeb1407ae2761bfb2f4a641714e212) Thanks [@joelhooks](https://github.com/joelhooks)! - chore: link plugin versions — sync claude-code-swarm-plugin with opencode-swarm-pluginView on GitHub ↗ -
Release notes excerpt
Patch Changes - Updated dependencies \[[35a81f3](https://github.com/joelhooks/swarm-tools/commit/35a81f38318ed08b835e7269405e8e53ed4599a5)]: - [email protected]View on GitHub ↗ -
Release notes excerpt
Patch Changes - [35a81f3](https://github.com/joelhooks/swarm-tools/commit/35a81f38318ed08b835e7269405e8e53ed4599a5) Thanks [@joelhooks](https://github.com/joelhooks)! - fix(publish): bump bun to 1.3.8 and add workspace dep resolution safety net Previous fix (0.63.1) still shipped with unresolved workspace:* because CI was pinned to bun 1.3.4 via packageManager. Bumps to 1.3.8 and replaces the inline one-liner with a proper publish script that verifies and resolves any leaked workspace:* references before uploading to npm.View on GitHub ↗