Synchronizes a shared, live development plan across teams of coding agents using git remote refs.
Also known as Leonhest/hivemind, hivemind-agents
- Stars
- 4
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Nov 3, 2026
- License
- MIT
What is hivemind MCP?
hivemind synchronizes a shared, live development plan across teams of coding agents using git remote refs. It exposes 8 tools, such as plan_get, task_claim, task_update.
Summary generated from the project's README
About hivemind MCP server
hivemind provides a way for teams of coding agents to stay synchronized by sharing a live development plan through git remote refs. Instead of using a central server or external accounts, the team uses their existing git repository as the source of truth. This allows multiple agents to coordinate on goals, tasks, API contracts, and project decisions without manual updates or merge conflicts. Each agent's changes are pushed to hidden refs, ensuring that teammates receive updates at their next tool call.
Users install the system via npx hivemind-agents install, which configures hooks for supported clients like Claude Code, Codex CLI, or Cursor. The system includes a background extractor that reads conversation transcripts to automatically pull out relevant information like schema changes or completed tasks. It also features a notebook for short-term status updates and a tidy command to keep the plan from becoming cluttered. Because it relies on git, all plan data stays within your existing repository and follows your current permission model.
What you can do with it
- 1Synchronize team development plansAsk an agent to create a shared roadmap for a group of developers working on a project.
- 2Detect breaking API changesNotify an agent immediately when a teammate modifies a shared schema or contract.
- 3Automate task managementHave the system automatically mark tasks as finished when a pull request is merged.
- 4Resolve plan contradictionsUse a review tool to identify and fix conflicting goals or decisions within the shared plan.
Written from the project's README. Every use case is checked against a quote from it.
How to install hivemind MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall hivemind MCP in Claude Code
$ claude mcp add hivemind -- npx -y hivemind-agents mcpInstall hivemind MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hivemind": {
"command": "npx",
"args": [
"-y",
"hivemind-agents",
"mcp"
]
}
}
}Install hivemind MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hivemind": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"hivemind-agents",
"mcp"
]
}
}
}Install hivemind MCP in VS Code CLI
$ code --add-mcp '{"name":"hivemind","type":"stdio","command":"npx","args":["-y","hivemind-agents","mcp"]}'Install hivemind MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hivemind": {
"command": "npx",
"args": [
"-y",
"hivemind-agents",
"mcp"
]
}
}
}Install hivemind MCP in Codex
$ codex mcp add hivemind -- npx -y hivemind-agents mcpInstall hivemind MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hivemind] command = "npx" args = ["-y", "hivemind-agents", "mcp"]
Install hivemind MCP in Gemini CLI
$ gemini mcp add -s user hivemind npx -- -y hivemind-agents mcpInstall hivemind MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hivemind": {
"command": "npx",
"args": [
"-y",
"hivemind-agents",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for hivemind-agents 0.1.1 in an isolated container with no network and no keys. It answered and listed 8 tools.
hivemind MCP tools 8
Read from the server with tools/listplan_getRead the team's shared plan: goals, contracts (APIs/schemas/types), decisions, tasks and open questions.
task_claimClaim a task so teammates know you are working on it. Call before starting a piece of work.
task_updateUpdate a task: progress note, status change, or mark done/blocked.
contract_publishPublish or change something other agents build against: an API route and its request/response shape, a DB schema, a shared type, an env var, or file ownership. Set breaking=true if existing consumers must change.
decision_logRecord a project decision teammates should follow (library choice, convention, architecture).
goal_setSet or change a project goal / scope statement.
questionAsk the team an open question, or answer one (providing answer closes it for discussion).
plan_removeRemove an obsolete entry from the plan.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableleonhest/hivemind is public and reachablegithub.com/leonhest/hivemind ↗Pass
- Package names this repository as its sourcehivemind-agents names leonhest/hivemind as sourcenpmjs.com/package/hivemind-agents ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/leonhest/hivemind ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from hivemind-agentsPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubhivemind
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 withnotebook_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 theplan_reviewtool) 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
| Agent | Plan at start | Updates mid-task | Auto-extraction | Notes |
|---|---|---|---|---|
| Claude Code | ✅ | ✅ every prompt and tool call | ✅ | |
| Codex CLI | ✅ | ✅ every prompt and tool call | ✅ | Approve the hooks once with /hooks in Codex (Codex requires this for any new hook) |
| Cursor | ✅ | ✅ after each tool call | ✅ | Built from Cursor's hook docs; not yet tested in a live Cursor session |
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 tidy find finished, duplicate and outdated entries (--apply to clean up)
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 disableturns it off for that clone;hivemind enableturns 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 -pwith Haiku (orcodex execif 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. SetHIVEMIND_EXTRACTOR_BACKEND=noneto 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
originremote 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
hivemind MCP questions
How do I add hivemind MCP to Claude Code?
Run claude mcp add hivemind -- npx -y hivemind-agents mcp in your terminal. Add --scope user to make it available in every project.
How do I add hivemind MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does hivemind MCP provide?
It exposes 8 tools, including plan_get, task_claim, task_update, contract_publish, decision_log.
How does hivemind sync data between team members?
It uses git remote refs to sync plan entries. Each person's plan entries live on their own hidden ref on your existing remote, avoiding merge conflicts.
Does hivemind require a central server or account?
No, there is no central server or account required; the team is synchronized through your existing git repository.
Is my plan data private?
Yes, your plan data never leaves your git host, meaning anyone with read access to the repo can read the plan, just like the code.