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

# Or run directly with npx
npx hivemind-mcp

export HIVEMIND_API_KEY=hm_live_xxx
npx hivemind-mcp

claude mcp add hivemind -- npx hivemind-mcp

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

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

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

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

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

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

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

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

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"}
  ])

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?")

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

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

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"]}
    ]}
  ])

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)

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

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

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");

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(...))

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

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

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

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Lint
pnpm run lint

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

# Convex dev server
pnpm run dev:convex

# Deploy Convex to production
pnpm run deploy:convex

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

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

# 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