# Hivemind

Persistent, append-only event log for AI agent coordination. Enables agents (Claude Code, Cursor, Codex CLI, custom scripts, CI pipelines) to publish, query, and react to structured events about project work — across tools, across sessions, and across time.

Hivemind is not an orchestrator, memory product, or workflow engine. It is the **coordination layer beneath all of them**.

![Hivemind Demo](demo.gif)

## Table of Contents

- [Quickstart](#quickstart)
- [Configure Your AI Tool](#configure-your-ai-tool)
- [How It Works](#how-it-works)
- [MCP Tools](#mcp-tools)
- [Event Types](#event-types)
- [Features](#features)
- [SDKs](#sdks)
- [REST API](#rest-api)
- [Dashboard](#dashboard)
- [Environment Variables](#environment-variables)
- [Architecture](#architecture)
- [Development](#development)
- [License](#license)

## Quickstart

```bash
# Install the MCP server
npm install -g @hivemindai/mcp-server

# Or run directly with npx
npx hivemind-mcp
```

**Local mode** works out of the box — no account, no API key, no network. Events are stored in `~/.hivemind/events.db` (SQLite) with local embeddings.

**Cloud mode** unlocks multi-agent coordination, the web dashboard, triggers, workflows, approvals, and cross-project intelligence:

```bash
export HIVEMIND_API_KEY=hm_live_xxx
npx hivemind-mcp
```

Get your API key at [hivemind.dev](https://hivemind.dev).

## Configure Your AI Tool

### Claude Code

```bash
claude mcp add hivemind -- npx hivemind-mcp
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "hivemind": {
      "command": "npx",
      "args": ["hivemind-mcp"]
    }
  }
}
```

### Windsurf

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "hivemind": {
      "command": "npx",
      "args": ["hivemind-mcp"]
    }
  }
}
```

### Any MCP-Compatible Tool

Hivemind uses stdio transport. Point your tool at `npx hivemind-mcp` and it will auto-detect local or cloud mode based on whether `HIVEMIND_API_KEY` is set.

## How It Works

```
Agent publishes event → embedding generated → stored in append-only log → other agents query/subscribe
```

Every meaningful action an agent takes — starting a task, making a decision, hitting a blocker, completing work — becomes a structured event with a vector embedding, stored permanently. Project memory, project state, and lightweight orchestration all compose on top of this log.

### Two Modes

| Mode | Storage | Embeddings | Auth | Network |
|------|---------|-----------|------|---------|
| **Local** (default) | SQLite at `~/.hivemind/events.db` | transformers.js (384 dims) | None needed | None |
| **Cloud** | Convex (PostgreSQL + vector index) | OpenAI text-embedding-3-small (1536 dims) | `HIVEMIND_API_KEY` | Yes |

## MCP Tools

### Core Tools (local + cloud)

| Tool | Description |
|------|-------------|
| `hivemind_publish` | Publish an event to a channel with structured data |
| `hivemind_query` | Semantic search + structured filters (channel, event_type, time range) |
| `hivemind_subscribe` | Register interest in event patterns, returns recent matches |
| `hivemind_status` | Aggregated project status: active tasks, completions, blockers |
| `hivemind_lock` | Acquire or release advisory resource locks |

### Extended Tools (cloud only)

| Tool | Description |
|------|-------------|
| `hivemind_blockers` | List unresolved blockers across the project |
| `hivemind_remember` | Semantic memory search across all channels |
| `hivemind_tasks` | View derived task state (active, completed, failed, blocked) |
| `hivemind_context` | Your organizations, teams, and roles |
| `hivemind_teams` | List teams you have access to |
| `hivemind_trigger` | Manage event-driven triggers (emit events or call webhooks) |
| `hivemind_approvals` | Human-in-the-loop approval requests and policies |
| `hivemind_knowledge` | Curated knowledge base: add, search, update docs |
| `hivemind_skill` | Auto-injected instructions triggered by file/tool/keyword patterns |
| `hivemind_workflow` | Define and run DAG-based multi-step workflows |
| `hivemind_schedule` | Cron-based and event-based scheduling |
| `hivemind_handoff` | Formally pass work between agents with context bundling |
| `hivemind_plan` | GSD-style structured planning with wave-based parallel execution |

## Event Types

Hivemind defines standard event types for common agent activities. You can also use `custom.*` for anything else.

| Type | Description |
|------|-------------|
| `task.created` | Agent starts a new task |
| `task.completed` | Task finished successfully |
| `task.failed` | Task failed |
| `task.blocked` | Task blocked by a dependency or error |
| `task.unblocked` | Blocker resolved |
| `decision.made` | Architecture or design decision recorded |
| `file.locked` | Advisory lock acquired on a resource |
| `file.released` | Lock released |
| `review.requested` | Code review needed |
| `review.completed` | Review finished |
| `bug.found` | Bug discovered or reported |
| `deploy.ready` | Deployment candidate ready |
| `schema.migration` | Database schema change |
| `custom.*` | Any user-defined event type |

### Event Structure

```json
{
  "id": "01HQXYZ...",
  "project_id": "proj_abc",
  "channel": "backend",
  "event_type": "task.completed",
  "source": {
    "agent": "claude-code",
    "tool": "mcp-server",
    "session": "sess_123"
  },
  "data": {
    "description": "Implemented user authentication",
    "files_changed": ["src/auth.ts", "src/middleware.ts"]
  },
  "confidence": 0.95,
  "created_at": "2026-02-23T10:30:00Z"
}
```

Tasks are **derived from the event stream**, not stored separately. A `task.created` event creates a task, `task.completed`/`task.failed` resolves it, `task.blocked`/`task.unblocked` changes its status. The event log is the single source of truth.

## Features

### Semantic Search

Every event gets a vector embedding at publish time. Query with natural language:

```
hivemind_query(query: "authentication changes", channel: "backend")
```

Combines free-text semantic search with structured filters (channel, event_type, time range).

### Advisory Locks

Resource-based locks for graceful conflict detection between agents:

```
hivemind_lock(action: "acquire", resource: "src/db.ts")
hivemind_lock(action: "release", resource: "src/db.ts")
```

- Any string as resource identifier (file paths, resource names, etc.)
- Agent + tool metadata stored with each lock
- Force-override with approval for stuck locks
- Automatic cleanup of expired locks

### Triggers

Pattern-match on events and automatically take action:

```
hivemind_trigger(action: "create", name: "deploy-on-ready",
  match_event_type: "task.completed", match_channel: "backend",
  action_type: "emit", emit_event_type: "deploy.ready", emit_channel: "ops")
```

- Exact and glob pattern matching (`task.*`)
- Data field conditions (`{"status": "ready"}`)
- Aggregation modes: `all` (AND), `any` (OR), `count` (threshold)
- Actions: emit a new event or call a webhook URL

### Human-in-the-Loop Approvals

Agents can request human approval before taking sensitive actions:

```
hivemind_approvals(action: "request", channel: "backend",
  description: "Schema migration: add users table",
  action_type: "schema-change")
```

- Approval queue visible in the dashboard
- Policies auto-require approval for resource patterns (e.g., `src/db/**`)
- Scopes: `one-time`, `session`, `standing`

### DAG Workflows

Define multi-step, multi-agent pipelines as directed acyclic graphs:

```
hivemind_workflow(action: "create", name: "deploy-pipeline",
  nodes: [
    {"nodeId": "test", "type": "task", "label": "Run tests"},
    {"nodeId": "review", "type": "gate", "label": "Human review"},
    {"nodeId": "deploy", "type": "task", "label": "Deploy to prod"}
  ],
  edges: [
    {"from": "test", "to": "review"},
    {"from": "review", "to": "deploy"}
  ])
```

- Node types: task, gate, condition, parallel
- Trigger workflows on cron schedules or events
- Track run status and history

### Knowledge Base

Curated documents with vector embeddings for semantic retrieval:

```
hivemind_knowledge(action: "add", title: "Auth Architecture",
  content: "We use JWT tokens with...", tags: ["auth", "architecture"])

hivemind_knowledge(action: "search", query: "how does authentication work?")
```

### Skills (Auto-Injected Instructions)

Define instructions that auto-inject into agent context based on triggers:

```
hivemind_skill(action: "add", name: "react-conventions",
  instructions: "Use functional components, prefer hooks...",
  trigger_files: ["*.tsx", "src/components/**"],
  trigger_keywords: ["component", "react"])
```

### Agent Handoffs

Formally pass work between agents with full context:

```
hivemind_handoff(action: "request", channel: "backend",
  target_agent: "agent-2",
  description: "Continue implementing the payment flow",
  context: {"files_changed": ["src/payments.ts"], "decisions": [...]})
```

### Structured Plans (GSD-Style)

Create phased execution plans with dependency-aware wave-based parallelism — inspired by the [Get Shit Done](https://github.com/gsd-build/get-shit-done) framework:

```
hivemind_plan(action: "create", name: "v2-migration",
  goal: "Migrate API to v2",
  phases: [
    {"name": "Research", "gate": "human", "steps": [
      {"id": "s1", "description": "Audit current endpoints"},
      {"id": "s2", "description": "Map breaking changes"}
    ]},
    {"name": "Execute", "steps": [
      {"id": "s3", "description": "Update auth module", "files": ["src/auth.ts"]},
      {"id": "s4", "description": "Update user module", "files": ["src/users.ts"]},
      {"id": "s5", "description": "Integration tests", "dependencies": ["s3", "s4"]}
    ]}
  ])
```

- **Wave computation**: Steps are automatically grouped by dependency depth. Independent steps run in parallel (wave 0), dependent steps wait (wave 1+)
- **Phase gates**: `auto` advances automatically when all steps complete; `human` requires explicit advancement
- **Progress tracking**: Real-time completion percentages per phase with visual progress bars
- **Decision log**: Record architectural decisions tied to the plan
- **Event integration**: Every plan action publishes events to the log for full traceability

```
hivemind_plan(action: "waves", plan_id: "plan_ABC123")
# Returns:
# Wave 0 (3 tasks — can run in parallel): s3, s4
# Wave 1 (1 task): s5 (deps: s3, s4)
```

### Conflict Detection

When a `task.created` event is published, Hivemind automatically checks for semantically similar active tasks and returns warnings if another agent is working on overlapping work.

### Context Synthesis

Search project memory across all channels with natural language:

```
hivemind_remember(query: "what decisions were made about the database?")
```

Groups results by channel for a comprehensive view of project knowledge.

### Scheduling

Run workflows or emit events on cron schedules:

```
hivemind_schedule(action: "create", name: "nightly-tests",
  cron_expression: "0 0 * * *",
  action_type: "run_workflow", workflow_id: "...")
```

## SDKs

### TypeScript

```bash
npm install @hivemindai/sdk-ts
```

```typescript
import { HivemindClient } from "@hivemindai/sdk-ts";

const client = new HivemindClient({ apiKey: "hm_live_xxx" });

// Publish an event
await client.publish({
  channel: "backend",
  event_type: "task.completed",
  source: { agent: "my-agent", tool: "cli" },
  data: { description: "Implemented auth" },
});

// Semantic search
const results = await client.query({
  channel: "backend",
  query: "authentication changes",
  limit: 10,
});

// Project status
const status = await client.status();

// Advisory lock
await client.lock("src/db.ts", { agent: "my-agent" });

// Triggers
await client.createTrigger({
  name: "deploy-on-ready",
  match_event_type: "task.completed",
  match_channel: "backend",
  action_type: "emit",
  emit_event_type: "deploy.ready",
  emit_channel: "ops",
});

// Workflows
const run = await client.runWorkflow("workflow-id");
```

Zero dependencies. Built-in retry logic. Methods for all cloud features (triggers, workflows, approvals, knowledge, skills, schedules, handoffs).

### Python

```bash
pip install hivemind-sdk
```

```python
from hivemind import HivemindClient, HivemindSyncClient, PublishParams, EventSource

# Async client
async with HivemindClient(api_key="hm_live_xxx") as client:
    await client.publish(PublishParams(
        channel="backend",
        event_type="task.completed",
        source=EventSource(agent="my-agent", tool="cli"),
        data={"description": "Implemented auth"},
    ))

    status = await client.status()
    results = await client.query(QueryParams(channel="backend"))

# Synchronous client
client = HivemindSyncClient(api_key="hm_live_xxx")
client.publish(PublishParams(...))
```

Requires Python 3.10+. Both async and sync clients with retry logic.

## REST API

The REST API is served by Convex HTTP actions. All endpoints require `Authorization: Bearer hm_live_xxx` (except `/health`).

### Events

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/v1/events` | Publish an event |
| GET | `/v1/events` | Query events (semantic search + filters) |
| GET | `/v1/events/:id` | Get a single event |

### Status & Tasks

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/status` | Active tasks, recent completions, blockers |
| GET | `/v1/tasks` | Derived task state from event stream |
| GET | `/v1/progress` | Task completion metrics |

### Coordination

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/v1/locks/:resource` | Acquire a lock |
| DELETE | `/v1/locks/:resource` | Release a lock |
| POST | `/v1/subscriptions` | Register a webhook subscription |
| GET/POST | `/v1/triggers` | List/create triggers |
| PATCH/DELETE | `/v1/triggers/:id` | Update/delete a trigger |
| POST/GET | `/v1/approvals` | Approval requests |
| POST | `/v1/approvals/:id/approve` | Approve/deny a request |
| GET/POST | `/v1/approvals/policies` | Approval policies |
| POST/GET | `/v1/handoffs` | Agent handoffs |

### Plans

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET/POST | `/v1/plans` | List/create plans |
| GET/DELETE | `/v1/plans/:id` | Get/delete a plan |
| GET | `/v1/plans/:id/status` | Plan progress with completion percentages |
| GET | `/v1/plans/:id/waves` | Wave-ordered steps for current phase |
| POST | `/v1/plans/:id/advance` | Advance to next phase |
| POST | `/v1/plans/:id/step` | Update step status |
| POST | `/v1/plans/:id/decide` | Record a decision |

### Workflows & Scheduling

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET/POST | `/v1/workflows` | List/create workflows |
| POST | `/v1/workflows/:id/run` | Execute a workflow |
| GET | `/v1/workflows/:id/runs` | Run history |
| GET/POST | `/v1/schedules` | List/create schedules |

### Knowledge & Intelligence

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET/POST | `/v1/knowledge` | Knowledge base CRUD |
| GET/POST | `/v1/skills` | Skill management |
| GET | `/v1/memory/decisions` | Recent decisions |
| GET | `/v1/memory/entities` | Knowledge graph entities |
| POST | `/v1/intelligence/conflicts/check` | Conflict detection |

### Health

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check (no auth required) |

## Dashboard

The web dashboard at [hivemind.dev](https://hivemind.dev) provides a full UI for managing your Hivemind projects.

| Page | Description |
|------|-------------|
| **Dashboard** | Overview with quick stats and recent activity |
| **Events** | Browse, filter, and inspect all events |
| **Live** | Real-time agent activity stream |
| **Search** | Semantic search interface |
| **Traces** | Execution trace visualization |
| **Workflows** | DAG workflow builder and runner |
| **Schedules** | Cron and event-based trigger management |
| **Approvals** | Approval queue and policy management |
| **Knowledge** | Knowledge base documents and skills |
| **Errors** | Error group analysis |
| **Analytics** | Usage charts and token savings metrics |
| **Org Intelligence** | Cross-project pattern detection |
| **Teams** | Team management and permissions |
| **Account** | API key management and rotation |
| **Settings** | Billing (Stripe) and org member management |

Real-time updates via Convex subscriptions — no polling.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `HIVEMIND_API_KEY` | For cloud mode | API key (`hm_live_xxx` or `hm_test_xxx`) |
| `HIVEMIND_API_URL` | No | Override the default API URL |

**API Key Format:**

```
hm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   (production, 40 chars)
hm_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   (testing, 40 chars)
```

When `HIVEMIND_API_KEY` is not set, the MCP server runs in local mode with SQLite and local embeddings.

## Architecture

```
                    +-----------------+
                    |   Dashboard     |  Next.js + Clerk
                    |  (analytics,    |  Real-time via Convex
                    |   management)   |  subscriptions
                    +--------+--------+
                             |
                    +--------v--------+
                    |  Convex Backend  |  Serverless functions
                    |  (HTTP actions,  |  PostgreSQL + pgvector
                    |   mutations,     |  OpenAI embeddings
                    |   queries)       |
                    +--------^--------+
                             |
              +--------------+--------------+
              |              |              |
     +--------+------+ +----+----+ +-------+-------+
     | MCP Server    | | TS SDK  | | Python SDK    |
     | (stdio/local) | | (HTTP)  | | (HTTP)        |
     +--------+------+ +----+----+ +-------+-------+
              |              |              |
     +--------+------+ +----+----+ +-------+-------+
     | Claude Code   | | Custom  | | CI/CD         |
     | Cursor        | | Scripts | | Pipelines     |
     +---------------+ +---------+ +---------------+
```

### Monorepo Structure

```
hivemind/
├── convex/                 # Convex backend (schema, functions, HTTP router)
├── packages/
│   ├── core/               # Shared: schemas, types, DB adapters, auth, embeddings
│   ├── mcp-server/         # MCP server (17 tools, stdio transport, local + cloud)
│   ├── sdk-ts/             # TypeScript SDK (HivemindClient)
│   ├── sdk-py/             # Python SDK (async + sync clients)
│   └── dashboard/          # Next.js web dashboard
├── scripts/                # Demo, seed, and setup scripts
└── docs/                   # Documentation
```

### Tech Stack

| Layer | Technology |
|-------|-----------|
| Runtime | Node.js 22 + TypeScript 5.4 |
| Monorepo | Turborepo + pnpm workspaces |
| Backend | Convex (serverless functions + database + vector search) |
| Database (cloud) | Convex-managed PostgreSQL + pgvector |
| Database (local) | SQLite + sqlite-vec |
| Embeddings (cloud) | OpenAI text-embedding-3-small (1536 dims) |
| Embeddings (local) | transformers.js / all-MiniLM-L6-v2 (384 dims) |
| MCP | @modelcontextprotocol/sdk (stdio transport) |
| Dashboard | Next.js 15 + React 19 + Tailwind CSS 4 |
| Auth | Clerk (dashboard) + API keys (SDK/API) |
| Payments | Stripe |

## Development

### Prerequisites

- Node.js 22
- pnpm 9.15+

### Setup

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Lint
pnpm run lint
```

### Dev Servers

```bash
# MCP server (watches for changes)
pnpm run dev:mcp

# Convex dev server
pnpm run dev:convex

# Deploy Convex to production
pnpm run deploy:convex
```

### Python SDK

```bash
cd packages/sdk-py
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

### Build Order (Turborepo)

```
core → sdk-ts → mcp-server → dashboard
              → sdk-py (independent)
```

### Publishing

```bash
# MCP Server → npm
cd packages/mcp-server && npm publish

# TypeScript SDK → npm
cd packages/sdk-ts && npm publish

# Python SDK → PyPI
cd packages/sdk-py && python -m build && twine upload dist/*

# Convex Backend
npx convex deploy
```

## License

MIT