Swarm Tools: Git-Backed Task State and Local Embeddings for OpenCode Agents
🐝 Multi-agent swarm coordination for OpenCode with learning capabilities, agent issue tracking, and management
At a glance
- What is it?
- Swarm Tools is a TypeScript coordination layer for OpenCode and Claude Code that keeps multi-agent task state in a git directory called the Hive and agent messages in an embedded libSQL event log. It is worth adopting if you already run OpenCode and want parallel workers with file reservations; it is the wrong choice if you need a hosted control plane or a permissively documented licence.
- Who is it for?
- Adopt Swarm Tools if you already work inside OpenCode or Claude Code, you want task state that survives a session restart in a git directory you can inspect, and you are willing to run Ollama locally for embeddings.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 47 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode Swarm Tools is built around: context death
The README's own framing is blunt: multi-agent coordination that survives context death. That is the problem statement. An agent session ends, the context window is gone, and whatever the agent had planned or learned disappears with it unless something outside the model wrote it down. Swarm Tools addresses this by moving three kinds of state out of the context window and onto disk: tasks into a git-backed directory, coordination messages into an append-only event log, and reusable learnings into a semantic memory store.
The intended user is someone already running OpenCode or Claude Code who wants to hand a large task to several parallel workers without those workers overwriting each other's files. The README's worked example is /swarm "Add user authentication with OAuth", which the project describes as decomposing into subtasks, creating cells in the Hive, spawning workers with file reservations, coordinating through Swarm Mail, reviewing completions, and recording what worked. If your work is a single agent doing a single file edit, none of this machinery earns its cost.
Coordinator, workers, and file reservations: the actual data flow
The architecture diagram in the README shows one coordinator and N workers. The coordinator queries past sessions, picks a strategy, and decomposes the task. Each worker holds a file lock before touching code, and the diagram draws arrows from worker to worker, which suggests handoffs happen directly rather than only through the coordinator.
The locking primitive is swarmmail_reserve, called with a path glob and an exclusive flag, for example swarmmail_reserve({ paths: ["src/auth/*"], exclusive: true }). That is the mechanism that prevents two workers from editing the same file. It is a reservation recorded in the event log, not an operating system lock, so its guarantee depends on every worker going through the same reservation call. A worker that edits files without reserving them first is not stopped by anything described in the README.
Communication is swarmmail_send with a recipient list, subject and body. The README credits MCP Agent Mail as the inspiration for this coordination model and Electric SQL for durable stream patterns. The underlying primitives are named as DurableMailbox, DurableLock and DurableDeferred, built on libSQL as an embedded SQLite store for event sourcing. Everything is described as running locally with no external servers.
Hive, Hivemind and the event log are three separate stores
It is easy to read the README and assume one database. There are three storage layers, and they have different durability stories.
The Hive is a git-backed directory at .hive/ holding tasks, which the README calls cells. Because it is git-backed, task state syncs through your normal git workflow and survives a session end. The API surface shown is hive_create, hive_cells and hive_close, with hive_close taking an id and a reason string.
Hivemind is semantic memory. hivemind_store writes a piece of information with tags, and hivemind_find searches it by query. Embeddings come from Ollama, with a fallback to full-text search when embeddings are unavailable, according to the README.
Swarm Mail is the coordination layer, and the README states that all state is an append-only event log with event types including agent_registered, message_sent, file_reserved, file_released, checkpoint and outcome. Because it is event sourced, current state is a fold over history. That is good for auditability and bad for anyone who expects to delete a message and have it stay deleted.
Getting it running: two install paths and the config that actually matters
For OpenCode, the README gives two commands: npm install -g opencode-swarm-plugin followed by swarm setup. After that, /swarm "your task" works in any session.
The Claude Code path is longer. You still install the CLI globally with npm install -g opencode-swarm-plugin, then inside Claude Code you open /plugin, go to Manage marketplaces, add the marketplace joelhooks/swarm-tools, then install the swarm plugin from swarm-tools. The README states the MCP server starts automatically.
The CLI has five subcommands: swarm setup to configure the integrations, swarm doctor to check dependencies, swarm init to initialize a hive in the current project, swarm config to print config paths, and the setup step above. Bun is listed as required, Ollama as optional. The development workflow is bun install, then bun turbo build, then bun turbo test.
The configuration that matters most is the embedding model, set through environment variables. OLLAMA_MODEL defaults to mxbai-embed-large, and OLLAMA_HOST defaults to http://localhost:11434. The README lists supported models with their dimensions: mxbai-embed-large at 1024 dimensions, nomic-embed-text at 768, all-minilm at 384, and snowflake-arctic-embed at 1024. Changing the model changes the vector dimension, and the README does not describe a migration path for embeddings already written at a different dimension. Treat that setting as something to decide before you accumulate memory, not after.
The learning system is where the claims get thinner than the machinery
The README says every completion records duration, errors, files touched and success. Patterns mature through three named stages: candidate, established, proven. Anti-patterns are generated automatically when a failure rate exceeds 60 percent, and confidence decays over 90 days unless revalidated.
Those are specific, checkable rules, which is better than most projects manage. What the README does not explain is how a pattern moves from candidate to established, what weight the coordinator assigns to a proven pattern when picking a strategy, or how the 60 percent threshold is computed (per pattern, per task type, or globally). The diagram says the learning stage records an outcome and updates weights, but the weighting scheme is not documented in the supplied material.
The practical consequence: you can read the learning system's outputs, but you cannot reason precisely about why the coordinator chose one decomposition over another. If you need to explain an agent's decision to a reviewer, that gap matters. If you only need the swarm to get better over time without you tuning it, it matters less.
Where Swarm Tools is the wrong tool
The strongest constraint is locality. The README states everything runs locally with no external servers, using libSQL as an embedded store. That is a real benefit for setup and for data residency. It also means there is no shared queue: two developers on two machines running swarms are not coordinating through the same event log unless they are sharing the .hive/ directory through git, and git is a poor transport for high-frequency message traffic. The Hive syncs via git; the Swarm Mail event log lives in libSQL and the README does not describe syncing it across machines.
Second, the reservation model is cooperative. It works when every worker is a Swarm Tools worker that calls swarmmail_reserve. It does nothing about a human editing the same file, or a worker spawned outside the swarm.
Third, the dependency on Bun is non-negotiable per the README's dependency table. If your team is standardized on Node, this is an additional runtime to install and keep current.
Fourth, the licence situation deserves a flag rather than a shrug. The README ends with the line MIT, but the repository metadata shows the licence as unknown. Those two facts can coexist (the GitHub detector may simply not have matched the file), but you should read the LICENSE file at the commit you pin rather than relying on either signal. This is not legal advice, just a note that the two sources in front of you disagree.
How it differs from a general-purpose agent framework
The obvious comparison is a general agent framework that also supports subagents, such as the Superpowers project, which the README credits for verification patterns. The difference is in where state lives. A typical subagent setup keeps the plan in the parent agent's context and returns results as messages; when the session ends, the plan is gone. Swarm Tools pushes the plan into .hive/ as cells that persist across sessions and can be reviewed with git diff.
Against MCP Agent Mail, which the README credits as the inspiration for the coordination model, the distinction is scope. Agent Mail is a coordination layer. Swarm Tools wraps coordination together with a task tracker and a learning store, and ties the whole thing to OpenCode and Claude Code through a plugin and an MCP server.
If you only need agents to message each other, the lighter coordination layer is the better fit. If you need the task list to outlive the session and feed back into future decomposition, the combined package is the point. The cost of that combination is that you adopt three storage subsystems at once, and each one has its own failure mode.
Maintenance cost and what to check before you commit
The release cadence visible in the supplied material is high. opencode-swarm-plugin shows 0.63.1 and 0.63.2 both published on 2026-02-06, roughly 47 minutes apart, and swarm-mail shows 1.11.2 the same day. A 0.x plugin version at patch 63 means the API is not stable by semver convention, and the README's tool names (hive_create, hivemind_store, swarmmail_reserve) are the surface that would move.
Upgrading means running swarm doctor afterward to confirm Bun and Ollama are still detected, and re-checking your OLLAMA_MODEL setting, because a model swap changes embedding dimensions. If you pin the plugin globally with npm install -g, an upgrade is a reinstall, and every project on that machine moves at once. The README does not describe a per-project version pin for the global CLI, which is worth confirming before you roll this out to a team.
On licence: the README says MIT, the repository metadata says unknown, and the README also credits three external projects. Read the LICENSE file directly at your pinned commit before you redistribute anything.
Editorial conclusion
Adopt Swarm Tools if you already work inside OpenCode or Claude Code, you want task state that survives a session restart in a git directory you can inspect, and you are willing to run Ollama locally for embeddings. Do not adopt it if you need a documented licence before shipping (the repository states MIT in the README but the GitHub licence field is unknown, so confirm the LICENSE file at the commit you pin), or if your agents need to run against a shared remote queue rather than one local event store. Verify three things first: that swarm doctor reports Bun and Ollama as healthy on your machine, that the .hive/ directory lands where you expect in your repo, and that your embedding model choice matches the dimension your existing data was written with.
Community notes