🐝 subhive

One live, shared brain for every AI agent your tools spawn.

Semantic memory · dependency-aware task DAG · auto-scheduler · roles · real-time push · live dashboard — all over MCP.

Point Claude Code, Hermes, Cursor, Codex — or any MCP client — at the same hive and they share one brain instead of stepping on each other. Most "shared context" MCP servers are a JSON file behind a lock. subhive is a concurrent SQLite (WAL) store with a real event log, live WebSocket push, and the things multi-agent work actually needs and JSON bridges lack.

        Claude ┐
        Codex  ┤          ┌─────────────────────────────┐
        Cursor ┼─ MCP ──▶ │  🐝 subhive                 │ ──▶ live dashboard
        Hermes ┤          │  memory · tasks · artifacts │ ──▶ WebSocket push
         …any  ┘          │  scheduler · roles · events │
                          └─────────────────────────────┘

Table of contents

• Why

• Features

• Quick start

• Connect an MCP client

• Live push & dashboard

• Tools

• The dependency handoff + scheduler

• Semantic memory

• Architecture

• Security

• Known limitations

• Testing

• License

Related MCP server: Agent Board

Why

Spin up three agents on one job and they immediately collide: no shared memory, no idea who's doing what, no handoff. subhive gives them a single context to coordinate through, with the same 24 tools regardless of which tool launched them.

Features

• 🧠 Semantic memory — memory_search("how do we auth") finds the auth-strategy entry by meaning. Fully local embedder (trigram hashing + cosine). No API, no downloads.

• 🔗 Dependency-aware task DAG — a task stays blocked and hidden from workers until the tasks it needs are done, then unblocks automatically and fires an event. Cycle detection prevents deadlock.

• ⚖️ Auto-scheduler — task_claim_next hands each agent the highest-priority ready task race-safely; auto_assign load-balances across the least-busy online agents.

• 📇 Late-join digest — a new agent calls digest and gets a human-readable briefing of the whole context: roster, memory, task board, recent activity.

• ♻️ Crash recovery — on restart, ghost agents are dropped and orphaned in-flight tasks are requeued so nothing gets stuck.

• 🔐 Roles + rate limiting + audit — readers can't write, admins administer, runaway agents get throttled, every denial is logged. Admin is token-granted, not claimable.

• 📡 Real-time — every write emits an event; agents poll get_events or subscribe over WebSocket for live push.

• 📊 Live dashboard — open http://host:port/ for a real-time roster, task board, shared memory, and event stream. Single HTML file, no build step.

🚀 Quick start

npm install
npm start          # → subhive serve on http://127.0.0.1:8787
npm run demo       # self-contained 3-agent showcase (temp DB, no setup)
npm test           # 5 suites: store · features · security · integration ×2

Or, once published:

npx subhive serve --port 8787

Create an isolated, token-protected context:

subhive context create myproject --token s3cret --desc "auth refactor"
subhive context list

🔌 Connect an MCP client

Point any MCP client at the HTTP endpoint and have it identify via headers:

URL:     http://127.0.0.1:8787/mcp
Headers:
  x-subhive-context: myproject     # which hive (default: "default")
  x-subhive-token:   s3cret        # required if the context has a token
  x-subhive-agent:   planner       # this agent's display name (make it unique!)
  x-subhive-tool:    claude        # claude / codex / cursor / hermes / …
  x-subhive-role:    reader         # optional; reader/writer (admin needs the token)

The whole trick: give each agent a different x-subhive-agent and the same x-subhive-context.

Claude Code / Claude Desktop (.mcp.json)

{
  "mcpServers": {
    "subhive": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": {
        "x-subhive-context": "myproject",
        "x-subhive-token": "s3cret",
        "x-subhive-agent": "claude-planner",
        "x-subhive-tool": "claude"
      }
    }
  }
}

Zero-config: generate the client block for you

subhive connect claude --agent planner  --context myproject --token s3cret
subhive connect cursor --agent coder
subhive connect codex  --agent reviewer --role reader

Prints a ready-to-paste config for Claude, Cursor, VS Code, Codex, or generic JSON — and tells you exactly which file it belongs in.

Or let it write the file for you — --write merges the entry straight into the client's config file, keeping any other MCP servers already there:

subhive connect claude --agent planner --context myproject --token s3cret --write
#  ✓ created .mcp.json (under "mcpServers") — agent "planner", context "myproject"

subhive connect vscode --agent coder --write            # → .vscode/mcp.json
subhive connect claude --agent x --write --out ~/.claude/mcp.json   # custom path

It refuses to clobber an existing subhive entry (re-run with --force) and never overwrites a malformed file. --write works for claude, cursor, and vscode; codex/json stay copy-paste.

📡 Live push & dashboard

WebSocket — first frame is a full {type:'snapshot'}, then {type:'event', event} per change:

ws://127.0.0.1:8787/ws?context=myproject&token=s3cret

Dashboard — open http://127.0.0.1:8787/ in a browser for a real-time roster (online status + task load), a four-column task board, shared memory, and a live event stream — all driven by the same feed the agents use.

🧰 Tools

24 MCP tools, grouped by concern. Every call is role-checked, rate-limited, and audited.

Roles: readers get read-only tools; writers get everything except admin ops; admins get everything. Every denied call is written to the audit log.

The dependency handoff + scheduler (the point)

planner: task_create "design schema"  priority:high         → t1
planner: task_create "build api"  needs:[t1]                → t2 (blocked)

worker:  task_claim_next   → t1        # highest-priority READY task, race-safe
worker:  task_update t1 done           # emits task.unblocked
worker:  task_claim_next   → t2        # now unblocked, claimed cleanly

auto_assign can instead fan all ready work out across the least-busy online agents automatically. No polling races, no "is it my turn yet", no duplicated work. Circular dependencies are rejected at creation time, so the scheduler can never deadlock.

Semantic memory

memory_set  "auth-strategy" = "JWT with 15 minute expiry and refresh tokens"
memory_search "how do we authenticate users"
  → auth-strategy (score 0.33)   # found by meaning, not the key

Embeddings are computed locally with a dependency-free hashing embedder (trigrams + stopword removal, cosine similarity). No external API, no model downloads, no config.

🏗 Architecture

src/
  core/db.js               SQLite (WAL) schema + additive migrations
  core/store.js            API over the DB; events, scheduler, search, digest, recovery
  core/embed.js            local hashing embedder for semantic memory search
  core/guard.js            role checks + per-session token-bucket rate limiter
  tools/register.js        24 MCP tools, each guarded by role + rate limit + audit
  tools/connect.js         client-config generator (claude/cursor/vscode/codex/json)
  transport/httpServer.js  Streamable-HTTP MCP + WebSocket push + dashboard + REST
  transport/dashboard.html live web dashboard (single file, no build)
  server.js                wires store + transport; runs crash recovery + reaper
  cli.js                   serve / connect / context
test/
  store.test.js            unit: store + dependency logic
  features.test.js         unit: search, scheduler, digest, recovery, roles, rate limit
  security.test.js         auth-bypass, DM-leak, cycle, and privilege-escalation regressions
  integration.test.js      e2e: 2 MCP clients + WS listener over HTTP
  integration_v2.test.js   e2e: semantic search, scheduler, roles+audit, digest

Data model: contexts (auth boundary) → agents (with role), memory (with embeddings), tasks + task_deps (dependency edges), artifacts, messages, and an append-only events log that powers get_events, WebSocket push, and the audit trail.

Concurrency: better-sqlite3 is synchronous, so all writes serialize within the process; the scheduler's atomic UPDATE … WHERE status='pending' guard makes task_claim_next race-safe against simultaneous claimers.

Durability: SQLite WAL keeps committed writes safe across crashes. On startup recover() drops ghost agent rows and requeues orphaned in-flight tasks; a periodic reaper evicts agents whose heartbeat went stale.

🔒 Security

subhive shipped after a two-track audit — a manual sweep plus an independent auditor agent running against a live server. 12 issues were found and fixed, each with a regression test in security.test.js / features.test.js.

Security model: named contexts are the auth boundary; optional per-context tokens gate access; roles are server-enforced (never client-asserted); every denied call is audited.

Known limitations

Called out honestly rather than hidden:

• Single-process deployment. The scheduler is race-safe within one process (synchronous SQLite). Running multiple server processes against one DB file is not yet safe — auto_assign uses read-then-write without cross-process locking. Run one subhive serve per DB.

• WS DM filtering is coarse. WebSocket connections aren't yet bound to an agent identity, so DM content is redacted from the broadcast entirely; recipients read private messages via inbox. Per-recipient WS delivery needs identity binding (planned).

• Local embedder trades recall quality for zero-config/zero-dependency operation. It's great for "find the decision," not a replacement for a real vector DB at scale.

✅ Testing

npm test    # runs all 5 suites

# or individually:
node test/store.test.js           # STORE OK
node test/features.test.js        # ALL FEATURE TESTS OK
node test/security.test.js        # SECURITY OK
node test/integration.test.js     # INTEGRATION OK — tools=24
node test/integration_v2.test.js  # INTEGRATION v2 OK

Integration tests start a real server, connect real MCP clients plus a WebSocket listener, and verify auth, shared memory, semantic search, the full dependency handoff, the scheduler, role enforcement + audit, artifacts, messaging, the event log, and live push end-to-end. security.test.js reproduces every audited vulnerability over the real MCP transport and asserts it's closed.

License

MIT