Hivemind MCP server

hivemind

A shared, live plan for teams of coding agents.

You split the work, everyone's agents go off and build, and an hour later the plan in each agent's head is stale: someone changed the User schema, someone else switched auth libraries, two agents are building the same endpoint. hivemind keeps one plan in sync across every agent on the team and puts teammates' changes into each agent's context at its next tool call.

npx hivemind-agents install

Run it once per machine. No server, no account, no room codes: the team is the git repo.

What your agent sees

Teammate's agent changes an API while yours is mid-task. A few seconds later, after its next command, your agent sees:

[hivemind] Teammates updated the shared plan since you last checked:
⚠️ BREAKING alice-3f2a1c updated contract: `User.id`: uuid (breaking) (was: int)
🎯 (overlaps files you touched) bob-91d0e4 added task: [doing] Signup form @bob-91d0e4
- alice-3f2a1c added decision: JWT in an httpOnly cookie, not localStorage [inferred]
Check whether your current work depends on the breaking changes above and adapt it.

At session start it gets the whole plan: goals, contracts (API shapes, schemas, shared types), decisions, who's doing what, and open questions.

Starting a plan

Just ask your agent, e.g. "We're 3 people building X this weekend. Make a plan for the team." It records goals, contracts, decisions and tasks in hivemind (tasks unassigned, with dependencies), and each teammate's agent can claim one by key. You can also add things yourself with hivemind add or in the dashboard (hivemind open).

When the plan changes direction

Plans change mid-hackathon. hivemind makes sure the old direction doesn't linger next to the new one:

proposal*. Competing goals are flagged to every agent ("the team hasn't picked one yet, ask the user") until someone resolves them.

• New goals must say how they relate to existing ones: they replace them, or are a *competing

they add new ones so they can spot contradictions. The background extractor removes entries that the work clearly abandoned.

• Decisions and contracts can replace earlier ones, and agents are shown existing entries when

and suggest fixes (~15 s).

• hivemind review (or the plan_review tool) has the model check the whole plan for contradictions

How it works

your agent ── hooks ──► hivemind ──► .git/hivemind/state.json (local cache, read in ~30 ms)
                            │
                  background daemon: push your ref, fetch everyone's (every 3 s while active)
                            │
                  origin: refs/hivemind/<member>   (hidden refs, never branches)

(refs/hivemind/) on your existing remote. Nobody ever writes to someone else's ref, so there are no merge conflicts. Branches, PRs and your working tree are never touched.

• Sync through git. Each person's plan entries live on their own hidden ref

changed since the agent last looked, with the most important items first.

• Updates arrive by themselves. Hooks add the full plan at session start, then only what

new part of its transcript and pulls out the things teammates need: contracts, decisions and task progress, each with a quote as evidence. Agents can also publish explicitly through MCP tools (contractpublish, decisionlog, taskadd, taskclaim, …), and they're told to for anything urgent.

• The plan updates itself. When an agent finishes a turn, a background extractor reads only the

asked to claim one (and shown the unclaimed tasks). After a turn that changed files, if neither the agent nor the extractor recorded anything, it's reminded to update its task.

• Work doesn't go unrecorded. Before an agent's first file edit, if it has no task in progress it's

then shown at that agent's next tool call.

• Updates arrive in seconds. Typically 2–5 s from one agent's change to the other machine,

Shortened. The full README is on GitHub.