# hive 🐝

**A shared brain for Claude Code and its sub-agents (MCP server + CLI).**

Agents share **state, not conversations**: a fresh agent boots with a ~350-token compiled
working set instead of re-reading 30k tokens of files and transcripts. Decisions survive
across sessions and days, sub-agents inherit each other's results (never their chat logs),
and 50 parallel agents can write without clobbering each other.

> Golden rule: never make an agent pay tokens to read information it doesn't need — or pay twice for the same information.

Full design: [`docs/PLAN.md`](docs/PLAN.md).

---

## Install (global, like any CLI)

```sh
npm install -g hive-mcp
```

Or from source:

```sh
git clone https://github.com/HusseinTaha/hive-mcp.git && cd hive-mcp
npm install && npm run build
npm install -g .
```

Now `hive` works from anywhere. Data lives in one file: `~/.hive/ctx.db` (an existing
`~/.sharedctx/ctx.db` from older versions is adopted automatically).

## Set up a project (once per repo)

```sh
cd your-project
hive init
```

This does three things:

1. **`.mcp.json`** — registers the `hive` MCP server, giving every agent five tools (below).
2. **`.claude/settings.json`** — wires three hooks:
   - `SessionStart` → injects a <800-token bootstrap, so every session starts already knowing the project
   - `SubagentStop` → commits each sub-agent's final report to shared memory automatically
   - `PreCompact` → snapshots state before Claude Code compacts, so nothing is lost mid-session
3. **`CLAUDE.md`** — adds the one-line norm: bootstrap with `ctx_get`, save results with `ctx_commit`.

Restart Claude Code afterwards so it picks up the config.

## Daily use

You mostly don't do anything — that's the point. The hooks bootstrap every session and
capture every sub-agent's results. Your part is telling Claude things worth remembering,
in plain language:

- *"Commit to shared memory: we're using PostgreSQL because we need transactions."*
- *"Save the decision that access tokens expire in 15 minutes."*
- *"Check shared memory before proposing a database."*

And when you come back tomorrow, a new session already knows all of it.

### What agents get (the 5 MCP tools)

| Tool | What it does |
|---|---|
| `ctx_get` | The working set: objective, current tasks, blockers, hot decisions, recent changes, topic index — compiled to a budget (~350–800 tok). Pass `since=<last CURSOR>` on later calls to get only changes (~15–100 tok). `topic=auth` drills into one topic. |
| `ctx_search` | BM25 search over everything ever stored, ~40 tok/hit with `[e<id>]` provenance refs. Zero local hits → labeled results from your **other projects** (`[proj-a/e12] …`). |
| `ctx_commit` | Save results: what changed, decisions (key/value/reason), facts, open questions, task updates. Hard size caps — a commit is a telegram, not a memoir. |
| `ctx_task` | Lease-based task board: `claim` / `release` / `complete`. Two agents can never hold the same task; stale leases (30 min) are reclaimable; `complete` requires evidence. |
| `ctx_compile` | A bespoke context pack for one task description — relevance-ranked, so cold facts matching the task resurface and hot-but-unrelated ones drop. |

### What a bootstrap looks like

```
== acme-api @ a3f9c21 · CURSOR: 412 ==
OBJECTIVE: Ship v1 auth
NOW: refresh-token rotation (task#12, owner: backend-2)
BLOCKED: none
DECISIONS: db=PostgreSQL(relational+tx) | auth=JWT(15m access) | api=REST
CHANGED: login endpoint impl (backend-1, 2h ago, ev: tests/auth ✓)
OPEN: rate-limit login?
⚠ VERIFY: 'api routes complete' written @ b2e11f0 (HEAD moved)
TOPICS: auth(9k) db(6k) api-contracts(7k)
MORE: d:cors · q:session-invalidation — pull via topic= or ctx_search
```

~350 tokens replacing a 30k-token history dump. Superseded decisions never appear here,
but stay searchable forever — that's what stops agent #7 from re-proposing MongoDB.

## CLI reference

```
hive init                          wire up .mcp.json + hooks + CLAUDE.md in cwd, seed DB
hive status   [--project P] [--role R] [--budget N] [--topic T] [--since N]
                                   print the compiled working set (what agents see)
hive stats    [--project P]        context-spend telemetry per tool + est. savings
hive distill  [--project P]        heat decay + working-set pressure valve (also runs
                                   automatically every ~25 events)
hive compress [--project P] [--model M] [--dry-run]
                                   model-assisted fact compression via the claude CLI;
                                   originals kept in supersede chains
hive dump     [--project P]        raw append-only event log as JSON lines
hive bootstrap                     alias of status (used by the SessionStart hook)
```

**Environment:** `HIVE_DB` overrides the DB path; `HIVE_PROJECT` overrides the project key
(default: git-root basename). Legacy `SHAREDCTX_*` names still work.

## Why it saves ~90%+ of context tokens

| | Naive shared-history | hive |
|---|---|---|
| Tool schemas | ~2,000 (10 verbose tools) | ~840 (5 terse tools, CI-guarded) |
| Bootstrap | 20k–80k transcript / file re-reads | ~350–800 (hook-injected) |
| Refresh checks | full re-dump each time | ~15–100 (cursor deltas) |
| Handoff | poisons the next agent | ~200-tok structured commit |

Under the hood: append-only SQLite event log (WAL — 50 parallel writers, zero conflicts),
facts with supersede-chains (nothing is ever deleted), provenance + git-drift `⚠ VERIFY`
flags on volatile facts, evidence-gated completion, and a distiller that keeps the hot
working set ≤ ~1,500 tokens no matter how much knowledge accumulates.

## Development

```sh
npm test          # 39 tests: behavior, eval harness (50k-token seeded project),
                  # multi-process stress (20 writers / 12-way lease race), schema-token guard
npm run build     # tsc → dist/
npm install -g .  # reinstall the global CLI after changes
```

Roadmap M0–M4 from [`docs/PLAN.md`](docs/PLAN.md) is complete. Remaining work is field
tuning: use it on real projects and let `hive stats` + the eval harness drive ranking changes.