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

What belongs in the plan

The plan is for coordinating with teammates, not a log of each agent's work. Only what someone else needs to know or act on goes in: who is doing what, interfaces between people's work, team decisions, and questions for the team. An agent's own progress goes on its task. In a repo where only one person has ever worked, hivemind tracks just task status.

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 other people need, written on purpose (agents use note_add; the extractor never writes notes), expiring after 7 days: ("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.

Keeping the plan small

Plans that only grow stop being read. hivemind keeps them current on its own:

• The extractor records less: contracts are only interfaces other people's work depends on (APIs, schemas, env vars, shared types), not component props or internal function signatures; decisions are only project-wide rules. It also sees recent commits, so finished work gets marked done.
• A daily tidy (on plans with 40+ open entries, at most once a day per repo, by whoever's agent is active) closes what is superseded, duplicated or no longer true, marks tasks done that commits show finished, and moves status-like decisions to the notebook. Every change records its reason, and the run is logged in the notebook. Run it yourself with hivemind tidy (dry run) / hivemind tidy --apply.
• Tasks get concluded: when an agent session ends, hivemind reads the end of its conversation and settles the tasks it worked on: done, todo (with what's left) or blocked. While a session runs, the extractor also checks its earlier tasks, so one it finished or moved on from doesn't stay "doing". A task that names a PR ("PR 123", "PR #123") is marked done as soon as that PR is merged into the main branch, whoever merged it and whichever session was told. Unfinished tasks and questions nobody touches for a week are closed as abandoned. A task stuck in progress shows "(no update for 6d)" until then.

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/ (hidden refs, never branches)

• Sync through git. Each person's plan entries live on their own hidden ref (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.
• 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 ).

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 tidy find finished, duplicate and outdated entries (--apply to clean up) hivemind add [--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