Swarm coordinates agents through a git-backed hive and a local event log

The task tracker is a git directory, and one is committed here

The Hive is described as git-backed task tracking in .hive/, which is meant to survive sessions and sync through git rather than live in a temporary directory. Its three calls are create, cells and close, taking a title and a type, a status filter, and an id with a reason. That design has a visible consequence at the top of this repository: .hive/ sits in the root alongside AGENTS.md and package.json, so the tracker for the project that builds the tracker is checked in like any other file. The stated benefit is that the arrangement outlives a session; the cost is that a per-project directory now travels with the code, and swarm init is the command that creates one in whatever project you point it at.

Reservations are the whole conflict story

Swarm Mail is the actor-model layer between agents, and the README names three primitives inside it: DurableMailbox, DurableLock and DurableDeferred. The concrete surface is small. A worker reserves paths, optionally exclusively, and sends a message to another named worker with a subject and a body. Checkpoints are the third item on that list. The spawn step in the task flow is what leans on it, since workers are spawned with file reservations and the flow claims no conflicts. Nothing in the reservation call is fuzzy: you pass a path pattern such as src/auth/* and a boolean, so whether two agents can touch the same file is decided by the pattern you write rather than by any detection at merge time.

Six event names make up the entire state log

All state is an append-only event log, stored in embedded SQLite through libSQL. The log has six named events: agent_registered when an agent joins the swarm, message_sent for agent-to-agent communication, file_reserved and file_released around an exclusive lock, checkpoint for a progress snapshot, and outcome for the completion result. Reading that list tells you what the system considers worth recording: identity, conversation, ownership of paths, resumable progress, and a final verdict. There is no event for a cancelled task and no event for a retry, so a run that is abandoned mid-flight leaves a checkpoint and an acquisition behind without a matching release, which is the shape an append-only store takes when the outcome never arrives.

Confidence expires after 90 days and anti-patterns trigger at 60 percent

Every completion records duration, errors, files touched and success, and from that the learning system does three things. Patterns mature through candidate, then established, then proven. Anti-patterns generate themselves once a failure rate passes 60 percent. Confidence decays over 90 days unless the pattern is revalidated. Ninety days is the parameter worth noticing, because a project that nobody touches for a season comes back to a coordinator whose memory has expired, and the coordinator queries past sessions as its first step. The How It Works diagram shows that box listing three moves in order: query past sessions, pick strategy, decompose, then splitting into three branches that end in three worker boxes drawn side by side with nothing after them.

Four embedding models with fixed widths, and an FTS fallback

Semantic memory is the one part that can leave the machine, in the sense that it can fail to. Hivemind stores learnings and searches them later using Ollama embeddings, and falls back to FTS when they are unavailable. Ollama is listed as optional; Bun is the only hard requirement. Two environment variables control the model, with the defaults written into the commands: OLLAMA_MODEL defaults to mxbai-embed-large and OLLAMA_HOST defaults to http://localhost:11434. Four models are supported, and their dimensions are fixed and unequal: mxbai-embed-large at 1024d, nomic-embed-text at 768d, all-minilm at 384d and snowflake-arctic-embed at 1024d. switching between them changes the width of every vector already stored, and nothing in the CLI list suggests a reindex step. The two variables are set like this:

export OLLAMA_MODEL=nomic-embed-text  # Default: mxbai-embed-large
export OLLAMA_HOST=http://localhost:11434  # Default

The rest of the command surface is four entries: swarm setup to configure the OpenCode or Claude Code integration, swarm doctor to check dependencies including Ollama, swarm init to initialize a hive in the current project, and swarm config to show config paths.

Three releases on one February morning, and none since

The published releases cluster into a single day. [email protected] went out at 02:00 on 2026-02-06, [email protected] at 16:57 the same day and [email protected] at 17:04, seven minutes later. After that the tag stream stops, while the default branch was pushed on 2026-07-30. So the two packages this repository publishes, the plugin that OpenCode and Claude Code install and the mail layer under it, are both pinned at a February state, and the roughly five months of commits since then carry no version anyone can install by name. Both installs come from npm rather than from a checkout, which is what makes that gap matter in practice. For OpenCode the whole path is two commands:

npm install -g opencode-swarm-plugin
swarm setup

For Claude Code the same global install is still listed as a required first step, followed by adding joelhooks/swarm-tools as a marketplace and installing swarm through the plugin menu, after which the MCP server starts on its own.

Twelve working notes sit at the root of the monorepo

The root of this repository is part product and part notebook. Twelve markdown files sit there as working documents: BUGS-TO-FILE.md, COMPACTION-THRESHOLD-TUNING.md, DRIZZLE-MIGRATION-STATUS.md, FEATURE-CATALOG.md, IMPLEMENTATION-NOTES-EVENT-CAPTURES.md, IMPLEMENTATION-SUMMARY.md, SECURITY_SUPPLY_CHAIN.md, SESSION_MESSAGE_SCANNING.md, SWARM-CONTEXT.md, SWARM-TESTING-GUIDE.md, TEST-ISOLATION-STATUS.md and TEST-STATUS.md. Underneath sits a Bun workspace with apps/* and packages/*, turbo.json, a .turbo/ directory and bun.lock, with packageManager pinned to [email protected]. The root scripts show how releases move: ci:version runs changeset version && bun update and ci:publish runs bash scripts/ci-publish.sh, while test:integration and eval:ci both reach into packages/opencode-swarm-plugin. An overrides entry pins @types/node to 22.19.3.

MIT is asserted in the README and no LICENSE file sits at the root

The last line of the README is MIT, and the licence field the repository metadata reports is empty rather than a licence identifier. The root directory holds no LICENSE file. That leaves three sources disagreeing about the same question: a word at the bottom of the documentation, nothing in the metadata, and nothing on disk to check the wording against. Nothing here settles which one governs. The same pattern shows up in the smaller claims: the How It Works diagram is cut off after three empty worker boxes, and the credits name MCP Agent Mail, Electric SQL and Superpowers as the sources of the coordination, durable stream and verification patterns respectively. Anyone building on this should settle the licence question directly with the author rather than infer it.

Editorial conclusion

Swarm fits teams that already run coding agents in OpenCode or Claude Code and want task state, file reservations and past learnings to outlive a single session, since all three survive a restart by design. It is a poor fit for a one-off task, because setup, a git-backed directory and an optional Ollama install are the price of admission, and its five not-yet adapters are none of its problem while its six unsupported harnesses are. Before adopting it, run swarm doctor to see whether embeddings resolve, decide whether a .hive/ directory belongs in your repository, and pin a Bun version rather than tracking 1.3.8. Treat the published releases as a February snapshot: the last one shipped on 2026-02-06 while the branch has moved on since.

Frequently asked questions

Official sources

1. Issues
2. joelhooks/swarm-tools on GitHub
3. Project website
4. README
5. Releases