Hivemind

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).

Plan and notebook

hivemind keeps two things apart:

• The plan: goals, tasks, contracts, decisions, open questions. What the team agreed and is doing.
• The notebook: status, observations, measurements, environment state ("the lab box is busy until 14:00", "precision 0.82 on the eval set", "image built locally, not pushed"). Agents see the last 24 hours of notes at session start and can search the rest with notebook_get.

At session start agents see the most actionable things first (tasks in progress, then open tasks, contracts, decisions, questions, recent notes), with long sections capped so nothing important is cut off. Finished tasks and answered questions drop out of that view automatically.

When the plan changes direction

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

• New goals must say how they relate to existing ones: they replace them, or are a competing proposal. Competing goals are flagged to every agent ("the team hasn't picked one yet, ask the user") until someone resolves them.
• Decisions and contracts can replace earlier ones, and agents are shown existing entries when they add new ones so they can spot contradictions. The background extractor removes entries that the work clearly abandoned.
• hivemind review (or the plan_review tool) has the model check the whole plan for contradictions and suggest fixes (~15 s).

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)

• Sync through git. Each person's plan entries live on their own hidden ref (refs/hivemind/<member>) 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.
• Updates arrive by themselves. Hooks add the full plan at session start, then only what changed since the agent last looked, with the most important items first.
• The plan updates itself. When an agent finishes a turn, a background extractor reads only the 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 (contract_publish, decision_log, task_add, task_claim, …), and they're told to for anything urgent.
• Work doesn't go unrecorded. Before an agent's first file edit, if it has no task in progress it's 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.
• Updates arrive in seconds. Typically 2–5 s from one agent's change to the other machine, then shown at that agent's next tool call.

Supported agents

install detects which of these you have and configures each one (--only=claude,codex to choose).

Claude Code plugin (alternative)

/plugin marketplace add Leonhest/hivemind
/plugin install hivemind@hivemind

Same hooks and MCP tools, no npm needed. Use either the plugin or npx … install, not both.

Commands

install puts a hivemind command on your PATH (or use npx hivemind-agents <command>).

hivemind status       who's in the plan, last sync
hivemind plan         print the shared plan
hivemind open         live dashboard in your browser (and a form to add to the plan)
hivemind review       check the plan for contradictions
hivemind add <goal|task|contract|decision|question> <key> <text> [--breaking]
hivemind doctor       check that everything is wired up
hivemind disable      turn hivemind off for this clone (hivemind enable to undo)
hivemind uninstall    remove hooks and MCP config (your repos' plan data is left alone)

Privacy and cost

• Your plan data never leaves your git host. There's no hivemind server. Anyone with read access to the repo can read its plan refs, the same people who can read the code.
• Public repo = public plan. hivemind detects public GitHub repos and tells your agent (and hivemind status) so nobody is surprised. Don't want that? hivemind disable turns it off for that clone; hivemind enable turns it back on.
• Secrets are scrubbed. Every plan entry is checked for keys, tokens, passwords and connection-string credentials before it's written, and the extractor is instructed to leave out credentials, personal details, customer names and unfixed security issues.
• Extraction runs on your machine with your own agent login. It calls claude -p with Haiku (or codex exec if you only have Codex) using your existing subscription or API key: about $0.005 per extraction on API pricing, or a small slice of your subscription usage. Set HIVEMIND_EXTRACTOR_BACKEND=none to turn it off and rely on the MCP tools only.
• Only new parts of transcripts with real work in them (a request or a code change) get extracted. Read-only exploration is skipped.

Requirements and limits

• macOS or Linux, Node 20+, git, and a repo with an origin remote you can push to (without push access you still receive updates, but can't share yours).
• Tested with GitHub. Other hosts that accept custom refs should work; GitLab hasn't been tested yet.
• Not inside a git repo, or no origin? hivemind stays out of the way.

Troubleshooting

Run hivemind doctor. Logs are in .git/hivemind/ in each repo (hivemind.log, daemon.log, extract.log).

License

MIT