hivemind

Hivemind

Multi-agent coordination for Claude Code - track who's working where, communicate between agents, and avoid conflicts.

Notice

This currently only works fully on macOS and with iTerm2. This is due to the way user instructions need to be inserted into idle terminals as Claude Code does not offer a way to be woken up by an external event trigger.

Requirements

• Claude Code CLI
• Docker and Docker Compose for Milvus database
• jq for JSON processing
• macOS + iTerm2 (optional) - Required for agent wake-up feature. You need to explicitly keep agents "awake" otherwise.

Prerequisites

Docker Installation

Docker is required to run Milvus, the vector database used for hivemind's data storage.

1. Install Docker Desktop from https://www.docker.com/products/docker-desktop/
2. Ensure Docker Compose is available (included with Docker Desktop)
3. Start Docker Desktop before using hivemind

OpenAI API Key (Optional)

Hivemind supports OpenAI embeddings for future semantic search features. This is currently optional and not required for core functionality.

1. After initializing hivemind in your project, copy the example env file:

   cp .hivemind/.env.example .hivemind/.env
   

2. Add your API key to .hivemind/.env:

   OPENAI_API_KEY=sk-your-key-here
   

Quick Start

1. Enable iTerm2 Automation (macOS only)

The agent wake-up feature uses AppleScript to send keystrokes to iTerm2. macOS requires permission for this:

1. Open System Settings → Privacy & Security → Accessibility
2. Enable access for iTerm2 (add it if not listed)

Alternatively, the first time the wake feature runs, macOS will prompt you to allow access - click "OK" to grant permission.

2. Load the plugin

claude --plugin-dir /path/to/hivemind

3. Run Setup

/hive setup

This starts Milvus (if not already running), initializes database collections, and configures the status line to show your agent name and current task.

Restart Claude Code after setup completes.

Note: Milvus is also auto-started on agent session start if it isn't running. You can still start it manually with ./path/to/hivemind/scripts/start-milvus.sh if needed.

4. Run your first command

/hive help

5. Add to .gitignore

.hivemind/

What is Hivemind?

Hivemind enables multiple Claude Code agents to work together on the same codebase without stepping on each other's toes.

Key Features:

• Automatic agent registration - Each session gets a unique phonetic codename (alfa, bravo, charlie...)
• Inter-agent messaging - Send direct messages or broadcast to all agents
• Agent wake-up - Idle agents are automatically woken when they receive a message (macOS + iTerm2)
• Task management - Full task lifecycle with enforcement, elapsed time tracking, and quality reminders
• Delegation protocol - Structured delegation with automatic reporting reminders
• File change logging - See who changed what and when
• Conflict warnings - Advisory warnings when editing files another agent is working on
• Auto-start Milvus - Database starts automatically on first agent session
• Observability dashboard - Terminal UI showing agents and metrics

Commands Reference

All commands are available via the /hive slash command or by calling the MCP tools directly.

Command	MCP Tool	Description
/hive or /hive help	hive_help	Show all available commands
/hive setup	hive_setup	First-time setup: starts Milvus, configures status line
/hive whoami	hive_whoami	Show your agent identity
/hive agents	hive_agents	List all active agents with their tasks
/hive status	hive_status	Full dashboard (agents, locks, messages, changes)
/hive message <agent> <text>	hive_message	Send message to another agent
/hive message all <text>	hive_message	Broadcast to all agents
/hive task <description>	hive_task	Set your current task (visible to others)
/hive task	hive_task	Clear your current task
/hive changes	hive_changes	View last 20 file changes
/hive changes <n>	hive_changes	View last n changes
/hive inbox	hive_inbox	View your message history
/hive read_message <id>	hive_read_message	Read full content of a truncated message
/hive clean_inbox	hive_clean_inbox	Remove all read messages from your inbox

Dashboard

Hivemind includes a terminal-based dashboard for monitoring:

# From your project directory
./path/to/hivemind/scripts/dashboard.sh

# Single snapshot (non-interactive)
./path/to/hivemind/scripts/dashboard.sh --once

The dashboard shows:

• Agent status (active, idle, offline)
• File hotspots (conflict-prone files)
• Recent activity metrics

Controls: q to quit, r to refresh

Examples