Hivemind

Multi-agent coordination for Claude Code. Shared event log, plans, and tasks across multiple Claude sessions.

npm install -g @inixiative/hivemind

Then add to Claude Code:

claude mcp add hivemind -- hivemind-mcp

Or manually add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hivemind": {
      "command": "hivemind-mcp"
    }
  }
}

git clone https://github.com/inixiative/hivemind.git
cd hivemind
./setup.sh

Restart Claude Code and hivemind is active.

On startup, Claude receives context about the hivemind state:

hivemind: agt_7a3f2b joined myproject (main)
  session: abc123-def456
  active: agt_c4d5e6_alice

This info goes into Claude's system context (not printed to terminal). Claude knows its agent ID and can see other active agents.

Hivemind supports two lifecycle modes:

• Local mode (stdio): agents are tracked by PID and the coordinator marks agents dead when their process exits.
• Network mode (HTTP): agents are tracked by lease heartbeat (last_seen_at) and the coordinator marks agents dead when lease TTL expires.

Session start registers the agent, then status/events/query/task/emit calls refresh liveness in network mode.

See ARCHITECTURE.md for details.

Tools marked ✓ are auto-approved after ./setup.sh. Tools marked ✗ require confirmation.

Use this for single-machine/local Claude sessions:

bun run mcp

This preserves the existing MCP stdio behavior and local PID-based lifecycle.

Use this when multiple containers/processes need to share one hivemind:

HIVEMIND_API_TOKEN=replace-me \
PORT=8787 \
bun run mcp:http

The HTTP endpoint is:

http://0.0.0.0:$PORT/mcp

Network mode requires:

• Authorization: Bearer <HIVEMIND_API_TOKEN> on MCP HTTP requests
• Lease/heartbeat lifecycle (last_seen_at) with TTL sweeping (no PID liveness reliance)

• HIVEMIND_API_TOKEN: required for bun run mcp:http
• PORT: HTTP port for network mode (default 8787)
• HIVEMIND_REMOTE_URL: when set in hook/agent environments, session-start register/status calls go to remote MCP instead of local DB logic
• HIVEMIND_AGENT_LEASE_TTL_SECONDS: lease TTL for stale-agent sweep in network mode (default 180)
• HIVEMIND_NETWORK_MODE: liveness mode toggle (1/true enables lease-based mode). mcp:http enables this automatically.
• HIVEMIND_BASE: base directory for project DB/state (defaults to ~/.hivemind)

Shared hivemind service container:

docker run --rm -p 8787:8787 \
  -e HIVEMIND_API_TOKEN=supersecret \
  ghcr.io/inixiative/hivemind:latest \
  bun run mcp:http

Implementer/subject/oracle containers (each agent):

export HIVEMIND_REMOTE_URL=http://hivemind:8787/mcp
export HIVEMIND_API_TOKEN=supersecret

With HIVEMIND_REMOTE_URL set, src/hooks/sessionStart.ts registers and fetches status through the remote service, enabling shared coordination across isolated containers.

hivemind install    # One-time global setup
hivemind init       # Register current project
hivemind status     # Show project status
hivemind watch      # Live tail of events
hivemind join       # Join as an agent

{type}_{6hex}[_{label}]

• agt_7a3f2b_alice - Agent
• pln_e9d2c1_auth - Plan
• tsk_e9d2c1_001 - Task (inherits plan hex)
• evt_f1a2b3_00001 - Event
• wkt_a1b2c3 - Worktree

agent:register/unregister
plan:create/join/complete
task:create/claim/start/complete/block
decision, question, answer, note

Stored at ~/.hivemind/claude_hivemind_{project}/hivemind.db

Tables: agents, plans, tasks, events, worktrees

Format: yyyy/mm/dd hh:mm:ss TZ