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.

Table of Contents

• Quickstart
• Configure Your AI Tool
• How It Works
• MCP Tools
• Event Types
• Features
• SDKs
• REST API
• Dashboard
• Environment Variables
• Architecture
• Development
• License

Quickstart

# 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:

export HIVEMIND_API_KEY=hm_live_xxx
npx hivemind-mcp

Get your API key at hivemind.dev.

Configure Your AI Tool

Claude Code

claude mcp add hivemind -- npx hivemind-mcp

Cursor

Add to .cursor/mcp.json:

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

Windsurf

Add to your MCP configuration:

{
  "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

{
  "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 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

npm install @hivemindai/sdk-ts

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

pip install hivemind-sdk

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

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Lint
pnpm run lint

Dev Servers

# 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

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

# 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