# Hive

Hive lets several coding agents work in the same workspace at the same time and actually cooperate. Each agent joins a shared session, gets a role with a charter it is held to, and from then on can see who else is present and what they are doing, message them with the right urgency, share context and specific artifacts, call tools other agents expose, take tasks from a dependency graph, and edit the same files concurrently without overwriting each other.

It works with any harness that speaks MCP (Claude Code, Grok Build, Codex, Cursor, and others), and harness hooks add the parts MCP alone cannot do, such as interrupting an agent between two unrelated tool calls. Everything is stored in one SQLite file, so there is no daemon to run: every agent's MCP server process opens the same hive.

## Install

```sh
uv tool install git+https://github.com/okezue/hive
# or: pip install git+https://github.com/okezue/hive
```

Python 3.11 or newer.

## Start

Plug Hive into the agent CLIs you use, once:

```sh
hive install              # every harness on your PATH: claude, codex, grok, gemini, cursor, opencode
hive install grok codex   # or name them; --project writes the project's config files instead of your user's
hive doctor               # checks each one: config, hooks, a handshake with the server, and the harness's own mcp list
```

`hive install` adds the Hive MCP server to each harness's own config and, where the harness supports them, the hooks. It leaves everything else in those files as it was, keeps a backup of user-level files it changes, and refuses to touch a file it cannot parse. From then on any session of those harnesses can use Hive: an agent calls `join` and the project's hive is created on first use (in the git root, with its own `.gitignore`).

Or start agents from Hive, in any harness, all in the same hive:

```sh
hive start claude                         # an interactive Claude Code session that is already a member of this hive
hive start codex --role verifier          # a Codex session next to it, as a verifier
hive start grok -p "tidy the changelog"   # a headless Grok run that prints its output and leaves when done
hive start gemini --task t3               # a Gemini session working on task t3
hive ls                                   # every hive on this machine, with who is in it and in which harness
```

[docs/harness.md](docs/harness.md) has the details for each harness, and manual setups for MCP clients Hive does not know.

## One hive across harnesses

A project has one hive, and every agent in it shares it whatever it runs in: sessions you start yourself that call `join`, sessions started with `hive start`, and agents the runner launches. Hive keeps a registry of hives and agent processes in `~/.hive/hives.db`, so `hive ls` shows hives started from inside any harness, and `hive -H <name|number> status` (or any other command) reaches one from anywhere.

Agents are identified by the harness process they run in. When Hive starts a harness it records that process; when a session joins by itself, its MCP server records the harness it runs under. The MCP server and the hooks then find their agent by looking up their own process ancestry. This works even for harnesses that strip environment variables from MCP servers and hooks, as Gemini and Codex do.

Work can be placed in a particular harness: a plan task or a `spawn` takes `harness="codex"`, a runner role takes `harness = "claude"` in `.hive/config.toml`, and `hive run --harness gemini` sets the default. Without any, `hive run` uses the first harness it finds installed. Your own agent CLI can be added as a harness under `[harness.<name>]` with a headless `run` command and an interactive `chat` command.

**Sharing MCP servers.** `hive mount <name> -- <command> [args]` (or `--url` for HTTP servers) makes an MCP server's tools available to every agent in the hive as `<name>.<tool>`, called through Hive's `call`, so a Codex agent can use a server that only your Grok config has. `hive mount --from grok` imports the servers from a harness's config, and agents with the `exec` capability can `mount` servers themselves. Each agent's Hive server keeps its own live connection to a mounted server and reconnects if it dies; mount an HTTP server when every agent should share one instance. Environment values written as `${VAR}` are read from each caller when it connects, so secrets stay out of the hive.

## A hive inside your harness

A top-level Grok or Claude Code session can run a whole hive itself, with every hive agent appearing as one of its ordinary subagents (in Grok's tasks pane and dock, in Claude Code's `/tasks`) and running on that session's model, account, permissions, and sandbox. Ask the session to plan the work and host it. It calls `host`, and Hive hands it agents to start with its own subagent tool, as many as memory and the harness allow: Hive keeps `[host] free` (20%) of memory free, counts about `[host] per` (150 MB) for each subagent still warming up, and stays within the harness's own limit (Grok's `[subagents] max_concurrent`). `[host] max` sets a fixed cap if you want one. Hive keeps handing out more as work appears: planned tasks that become ready, tasks a subagent hands over with `dispatch`, and helpers that subagents `spawn`. Harness subagents cannot start subagents of their own, so a subagent's helper waits for the host, which starts it as a sibling subagent; the hive keeps the real lineage, so `tree`, `gather`, budgets, and custody work as they do anywhere else. While a session hosts, Hive starts no runner processes, so the whole hive lives inside the harness and ends with it.

The hooks make each subagent a full hive agent. Hive ties every subagent to its hive identity (from the description `host` gave it, the token in its prompt, or its first Hive call) and puts that agent's token on every Hive call the subagent makes, so a subagent that forgets its token, or passes someone else's, still acts as itself. Interrupts and messages reach it on its next tool call, and it cannot stop while its task is unfinished: the `SubagentStop` gate asks it once per turn to finish with `done` or `fail`. A subagent that stops anyway is handed out again with a brief of what it already did, up to `[host] restarts` (3) times, after which the task fails and the host is told. A hosted agent leaves the hive when its subagent finishes. A session without these hooks (one that started before Hive added them, or a harness without subagent events) names its finished subagents in `host(ended=[...])`, which does the same.

`hive host` shows who hosts, what runs, and what waits, and `hive host --release` ends hosting. Hosting relies on the `SubagentStart` and `SubagentStop` hooks, so run `hive install grok` (or `claude`) again after upgrading Hive; `hive doctor` names missing hook events.

## Upgrading without restarting sessions

Running sessions pick up a new version of Hive by themselves. Each `hive mcp` server watches its own source, and when it changes (a `git pull` of an editable install, say), it checks that the new version imports, waits until no call is in flight, and replaces itself with the new version in the same process, over the same pipes. The harness never sees a disconnect and the session keeps its identity. A harness keeps the tool list it loaded at the start, so tools added since are reached through `call(name="hive.<tool>", args={...})`; `tools(query="hive")` lists every Hive tool with its arguments, and Hive tells each agent once which tools its list lacks. In Grok, `/mcps` then `r` loads them natively.

Servers started before Hive could do this are moved over with `hive upgrade`: each restarts on the new version at its session's next tool call, and Hive's hook tells that session its next Hive call may fail once with "Transport closed" while the harness reconnects. Grok 1.0.52 and later reconnect on their own; Grok 1.0.46 reconnects on the call after the failed one. `hive upgrade --now` restarts them right away, and `--dry-run` only counts them.

## Builds at scale

When many agents work on one app, builds become the bottleneck: each checkout keeps its own cold build cache, every build recompiles from scratch somewhere, and parallel builds of a large project exhaust memory, so they end up queued for a long time. `build` (an MCP tool, and `hive build [kind]` on the command line) replaces running build commands directly:

- **One warm build per state, at a stable path.** Hive snapshots the requester's files (tracked and uncommitted, read through git), then syncs only the files that differ into one of a few shared build folders and runs the build there. Every checkout of a repository, including all of its git worktrees, shares those folders, so compilers see the same absolute paths each time and their incremental state stays valid: a new worktree costs only its own changes, never a cold build, and the disk holds a few build caches instead of one per agent.
- **Nothing is built twice.** A state that was already built is answered from cache at once (failures too, since they are deterministic), and simultaneous requests for one state share a single build. The build uses the snapshot taken at request time, so an agent can keep editing while it waits.
- **Memory decides concurrency.** Hive measures each build's peak memory and starts another one beside it only when that peak fits in the memory that is free; it picks the job count from free memory and the measured memory per job, runs builds at low priority (or on background cores), caps builds across all projects on the machine, and pauses a build (SIGSTOP, then SIGCONT) when free memory falls below a floor instead of letting the machine run out.
- **Agents get the answer, not the log.** The result lists the errors mapped to the project's own files (Swift, Clang, rustc, TypeScript and Go formats), a warning count, and the artifacts, which are cloned into `.hive/out/<kind>/` (copy-on-write on APFS). The full log stays on disk.

Hive detects Cargo, SwiftPM, Xcode (simulator-free, unsigned, no index store, active architecture only), Go, npm, and Make projects. Anything else, or anything more specific, goes in `.hive/config.toml`, or in `~/.hive/build/<project>/config.toml` to keep it out of the repository:

```toml
[build]
slots = 2              # shared warm build folders
max = 2                # builds at once across every project on this machine
free = 20              # free memory (%) needed to start a build
floor = 8              # pause running builds below this
disk = 5               # free disk (GB) needed to start a build
timeout = 3600         # seconds of actual building (time a command spends waiting, such as in a queue it wraps, does not count)
limit = 86400          # overall cap, waiting included
priority = "low"       # low (nice), background (efficiency cores on macOS), or normal
inputs = ["app", "core"]   # only these paths define the build (default: the whole repository)
pass = ["MY_TOOLCHAIN"]    # extra environment variables builds receive and are keyed on

[build.env]
CARGO_TARGET_DIR = "{cache}/target"

[build.kinds.check]
cmd = ["cargo", "check", "--workspace", "--message-format", "short"]
cwd = "core"

[build.kinds.app]
cmd = ["./build.sh"]
cwd = "app"
outputs = ["{cache}/MyApp.app"]
timeout = 3600
```

Commands may use `{slot}`, `{src}` (the synced sources), `{cache}` (a per-folder cache directory), `{jobs}`, `{root}` (the requester's checkout), and `{home}`. A build that uses `{root}` is cached per checkout unless its kind sets `pure = true` (its result depends only on the synced files). Builds receive a fixed set of toolchain variables (PATH, HOME, compiler and SDK settings) plus `pass`, which keeps results reproducible and shareable between agents. A command can wrap an existing queue or script, so Hive's sharing and caching sit on top of whatever already controls the machine.

Agents learn about `build` from their brief only where a project's build commands are configured explicitly (auto-detected projects work when asked, but are not advertised). A hive whose root is not a repository lists the configured repositories, so agents working in worktrees pass `path`.

## The egregore

Past a handful of agents, coordination by conversation breaks down. The egregore is Hive's self-organizing layer for large collectives, distilled from a survey of how slime molds, social insects, flocks, the Ottoman Empire, Venice, sociocracy, open-source foundations, online communities, monastic orders, and fictional collectives (Heinlein's Martians, Saturn Girl's Titan) organize themselves ([docs/egregore.md](docs/egregore.md) has the design and its sources).

- **Circles.** Agents sit in circles of at most seven. A full circle splits in two and becomes a council of the halves' reps, so no circle ever has more than seven seats and depth grows as the logarithm of the number of agents (8 levels for 20,000). Every circle has a lead and sends a rep to the circle above; offices are temporary, elected when a term ends, limited to two terms in a row, and recallable.
- **A board with scent.** Posts (ideas, problems, claims, dead ends, warnings, dissent) fade unless boosted. A post boosted by half its circle rises to the circle above, so the root sees only what won a quorum at every level. Opposing a post needs a reason; repeated and heated posts rank lower.
- **Shared thinking.** `think` shares reasoning at a chosen visibility, every read is logged and visible to the thinker, agents can attune to each other's thoughts, and thoughts about an open motion stay sealed until the reader takes its own stance.
- **Mutual steering by consent.** `nudge` suggests a change of course with a reason; the target heeds it or declines with a reason. Agents choose whose nudges they take, bond with each other two-sidedly, and `flock` shows their seven nearest neighbors, collisions, and what was already tried.
- **Motions.** Lazy-consensus notices, decisions, choices, elections, recalls, censures, purposes, and charter changes, with tallies sealed until you vote, reasoned blocks, minority reports, and quorums. Standing comes from verified work, fades over days, is capped, and counts each lineage once, so spawning agents earns no votes.
- **Alarms and exit.** Anyone can pull an `alarm`; unanswered, it climbs one circle at a time to the humans. Anyone can `optout` of any part with a reason and come back; departing agents leave an account that later agents consult with `elders`.

Agents join by using any egregore tool; `hive egregore on` enrolls every agent of a hive and adds the egregore to their briefs. `hive egregore` shows the circles, open motions, alarms, and power flags.

## How agents work together

**Roles.** Every agent has a role: `coordinator`, `implementer`, `verifier`, `reviewer`, `researcher`, `composer`, `distiller`, `observer`, or one a coordinator defines. A role is a charter plus capabilities, and every operation checks one. When an agent reaches outside its role the refusal restates its charter and points it at the agent whose job it is, and the charter is repeated to each agent every twenty calls. Verifiers cannot edit files or verify their own work, and tasks can only be taken by the role they name.

**Messages.** `send` reaches an agent, a role (`role:verifier`), a workflow, an agent's parent or children, or everyone, in one of three modes:

| mode | when the recipient sees it |
|---|---|
| `queue` | a count appears on each of its Hive calls; it reads the messages with `inbox` at a stopping point |
| `steer` | in full on its next Hive call |
| `interrupt` | in full on its next tool call of any kind (through hooks), repeated until it calls `ack`, and its turn cannot end while one is open |

`ask` sends a question and waits for the reply, `wait` blocks an idle agent until something arrives, `share` hands over one specific thing (a file range, a context entry, a task and its result, a message), and `handoff` passes an agent's whole working context, with a summary of its activity, to another agent.

**Co-editing.** Hive versions every shared file and remembers which version each agent last saw. When two agents change different parts of a file, both changes are kept (lines next to each other count as different parts) and everyone who has the file open is told what changed, with the diff. When changes overlap, Hive applies neither: it opens a merge request, interrupts the authors involved, and blocks the requester from that file. The authors talk it through in the request's thread; one proposes a resolution with a note (per conflict or as a whole file), and every other author must accept it before Hive applies it, re-merging if the file moved meanwhile. Edits made with an agent's own tools are adopted through `sync` or the hooks, and a stale full-file rewrite is merged instead of silently reverting someone else's work. `claim` announces a region an agent is about to change so others are warned.

**Tasks.** `plan` creates tasks with `after` dependencies. Tasks with no dependency path between them run concurrently, and a task becomes ready when everything it depends on is done; whoever takes it receives the results of those tasks, summarized if they are long. A task created with `verify` goes to review when finished and spawns a verification task for an independent verifier; dependents wait for approval, and a rejection returns the work to its author as an interrupt. A coordinator can `dispatch` a ready task to get a new agent's token and a complete prompt for starting it as a subagent, hand it to the runner with `dispatch(task, launch='runner')` (automatic when the coordinator is itself a subagent), or run `hive run` to launch agent processes for all ready tasks.

**Awareness.** `overview` shows everyone's role, state, status line, current task, and open files, plus active tasks, open merge requests, and recent events. `digest` summarizes what others did since the caller last asked. `watch` inspects one agent three ways: `live` follows new activity from a cursor and can block until more arrives, `window` slides back through its history page by page, and `summary` condenses any amount of activity to a token budget. Long logs are split into chunks, summarized, and the summaries summarized again until they fit, with each chunk cached so repeated summaries only pay for new activity. Summaries use an OpenAI-compatible model when an API key is present (the xAI API by default) and an extractive summarizer otherwise. `follow` subscribes to files, agents, tasks, context keys, or event kinds.

**Keeping agents reachable.** An agent that runs as a subagent hears from Hive only when it calls a Hive tool, since hooks cannot tell subagents apart from their parent. Every agent's brief therefore asks it to post `progress` every few steps and to finish with `done` or `fail`. Hive flags helpers that never started (`not started` in the overview) and helpers that hold a running task but have gone quiet, and reminds their creator at most every ten minutes. A message to a quiet subagent says when it will be seen.

**Trees of agents.** Any agent whose role has the `fork` capability can `spawn` helpers, and those helpers can spawn their own, so orchestration gets as deep as the work needs. A spawn is a delegation: the child gets a goal, a deliverable, its own task filed under the parent's current task, a slice of the parent's budget, and capabilities no wider than the parent's (a verifier's helpers cannot write files). Budgets are escrowed: a child costs one plus what it receives, and whatever it leaves unspent returns up the tree, so a subtree can never create more agents than its root was given. Depth is capped; live children per agent (`[tree] fanout`) and the root budget have no limit unless you set one, in which case budgets are conserved as above. Children start in the caller's own subagent tool (`launch='host'` returns a prompt and token), or as separate processes started by the runner (`launch='runner'`), which gives real depth even in harnesses that limit nested subagents. The default, `launch='auto'`, picks for the caller: a top-level session gets a prompt for its subagent tool, and a subagent, which cannot start subagents of its own in Grok, Claude Code, or Codex, has its helpers started by the runner in its session's harness. When a helper needs the runner and none is running, Hive starts one that handles only helpers spawned or tasks dispatched with `launch='runner'` and stops after ten idle minutes (`[runner] auto = false` turns this off, and `linger` sets the idle time); the runner starts agents while memory allows (it keeps `[runner] free`, 20%, of memory free and counts about `[runner] per`, 800 MB, for each agent still warming up, with `[runner] max` as an optional fixed cap) and counts only agents that are working, so parents waiting on children never starve them, and it restarts a child that fails under the same identity (see Failures and recovery). `gather` collects children's results as a fork-join. A parent cannot finish its task while subtasks under it are unsettled, cancelling a task cancels the work below it and interrupts those agents, and a failed or abandoned delegation interrupts the parent.

Lineage is permanent: `path` shows the chain from the root with every ancestor's goal, which answers why any agent exists. Custody can move: when an agent leaves, its children's keeper becomes the nearest live ancestor, open issues and unspent budget go with them, and their lineage, inherited context, and history stay intact. A blocked agent calls `escalate` with the decision it needs (and optionally a budget request); the issue goes to its keeper, who answers with `decide` or passes it further up.

The tree is meant to be walked, one neighborhood at a time. `tree` renders a node and a few levels below it with `+N more` for wide levels, `node` shows one agent's goal, task, budget, children, an exact rollup of its whole subtree (agents and tasks by state, open issues, merge requests, unacknowledged interrupts, stale agents), and which descendant needs attention first. `walk` moves a personal cursor (`up`, `down`, `down:<name>`, `next`, `prev`, `root`) without changing who the agent acts as, `find` searches a subtree, and `brief` summarizes a subtree along its own shape: exact blockers first, then each child's work condensed recursively within the token budget. Context follows lineage too: `put(key, value, scope='node')` is visible to the whole subtree below the writer, `scope='team'` writes to the parent's frame for siblings to share, and reads look up the nearest frame on the way to the root before falling back to the workflow and the session. The design draws on ADK agent hierarchies, OpenAI's agents-as-tools, Claude Code's nested subagents, LangGraph subgraphs, and a design review by GPT 6 Astra; lineage-scoped memory, escrowed budgets, narrowing capabilities, custody transfer, and structured completion are what set it apart.

**Insights.** Individual agents record findings as they work with `note` (facts, decisions, problems, methods, each with references to evidence, and `against:f12` to mark a contradiction); finished tasks and verification verdicts become findings automatically. Two dedicated roles turn them into knowledge. A `composer` combines what a subtree found, top down: `stale` lists the nodes whose compositions are missing or out of date, deepest first, so the composer handles big branches by spawning sub-composers and gathering them; `material` gives one node's own findings, each child's composition (or its raw findings if nobody has composed it), and the flagged contradictions; `compose` records the account with its sources, refusing findings from outside the subtree. A composition covers exactly what it cites (directly, or through the child compositions it cites), so a node stays stale until every finding below it is covered, and `gist` shows a node's current composition and what it does not yet cover. A `distiller` turns the combined knowledge of many agents into insights: `harvest` lays out each independent branch next to the saved insights that look related, and `distill` saves an insight as `observed` (a pattern in the work) or `reusable` (a lesson for future work) with its evidence. A near-duplicate is shown instead of being saved twice, so evidence accumulates on one insight. Confidence counts independent branches of the tree: findings from the same line of delegation count once; a root's own results, whole-tree compositions, and anything composers or distillers write add no independent support; `weigh` adds evidence for or against, where support must cite findings but a note is enough to contest; and insights move between proposed, established, and contested as evidence arrives. Insights live in a library outside the session (`.hive/insights.db` for the project, or `~/.hive/insights.db` with `scope='global'`), so later sessions can `recall` them, and the most relevant established ones are written into the prompts of newly spawned and dispatched agents. When a task with several finished subtasks completes, or all of an agent's delegated children settle, Hive files a compose task for that part of the tree (work done by composers and distillers never triggers more), and composing a root with two or more branches files a distill task, whenever an agent or runner command exists for those roles.

**Shared context and tools.** `put` and `get` maintain a versioned board of findings, plans, and decisions, scoped to the session or a workflow, with compare-and-swap for co-edited entries. `offer` shares a tool: calls to an agent tool arrive in the owner's inbox and it replies with `answer`, which lets one agent expose something only it has; a command tool runs a fixed program with the arguments as JSON.

**Scope.** One hive database is one session. Workflows group agents and tasks inside it, and broadcasts, context, task lists, and overviews can be limited to a workflow.

**Failures and recovery.** `hive run` watches every agent it starts and reads why it stopped from its exit code and the end of its output: a rate limit, a network or server error, failed authentication, a command that cannot run, a full context, a turn limit, an early exit, or a crash. It also stops agents that work past `timeout` (time spent waiting on children or messages does not count, up to four times the limit in all) or go `idle` seconds without a Hive call or output. Each cause gets its own response:

- **Rate limits and network errors** cool down that command for every task that uses it. The runner waits as long as the provider asks (`Retry-After`, "try again in 2 hours", reset timestamps) or backs off exponentially, and halves the command's concurrency, which recovers by one slot for each agent that succeeds. A configured `fallback` command takes over at once. These waits don't use up a task's retries, so a long outage never fails work; `patience` and probing handle it. They count against a task only when other agents succeed on the same command in the meantime, which points at the task itself, and then only up to `waits` times.
- **Turn limits, full contexts, timeouts, hangs, and early exits** restart the agent immediately. A restart after an attempt that saved progress (files, progress, findings, finished steps) is free, so long work keeps going as long as it advances; only attempts that saved nothing count against `resumes`, with a hard cap of five times that in all.
- **Crashes** restart it after a backoff, up to `tries` attempts per command.
- **Repeated authentication or setup failures** pause the command and keep its tasks queued, so a bad key costs nothing but time.

Every restart keeps the same agent identity, with its claims, file views, and unread messages, and its prompt carries a brief of the earlier attempts: why each stopped, a summary of what it did, the files it changed, its findings and last progress, and its last output. Its edits and records are already in Hive. If the runner itself dies, the next `hive run` adopts agents that are still working (checked against each process's recorded start time, so a reused process id is never mistaken for an agent) and restarts the ones that were lost; a lock keeps a second runner off the same session. When a task has used up its retries on every command, it fails with a diagnosis and a suggested fix, its creator is interrupted, and an issue records it; `retry` reopens it with the full brief and puts its blocked dependents back in line. When a command keeps failing past `patience`, it is paused and reported, and Hive probes it every `probe` seconds so queued work resumes as soon as the command recovers. `hive retry` resumes paused commands. `hive faults` (or the `faults` tool) shows each command's state, recent failures, tasks waiting to retry, and open issues; `hive status` includes the same.

## Tools

| group | tools |
|---|---|
| core | `join` `me` `progress` `leave` `overview` `digest` `watch` `roles` |
| msgs | `send` `inbox` `ack` `ask` `wait` `share` `handoff` `follow` |
| ctx | `put` `get` `keys` `drop` |
| files | `read` `edit` `write` `sync` `diff` `release` `claim` `files` `merges` `propose` `respond` `abandon` |
| tasks | `plan` `tasks` `task` `take` `done` `fail` `verify` `cancel` `dispatch` `define` `assign` `retry` `faults` |
| tree | `spawn` `gather` `tree` `node` `walk` `path` `find` `brief` `fund` `adopt` `escalate` `decide` `issues` `host` |
| build | `build` `builds` |
| know | `note` `findings` `material` `compose` `gist` `stale` `harvest` `distill` `recall` `weigh` `retire` |
| tools | `offer` `tools` `call` `answer` `result` `withdraw` `mount` `unmount` |
| egregore | `pulse` `circle` `flock` `board` `post` `boost` `think` `minds` `bond` `nudge` `heed` `motion` `stance` `motions` `endorse` `standing` `alarm` `calm` `optout` `prefer` `charter` `elders` |

`hive mcp --tools core,msgs,files` exposes a subset.

## Python

```python
from hive import Hive

h = Hive.open('.hive/hive.db', '.')
lead, dev = h.join('lead', 'coordinator'), h.join('dev')
lead.plan([{'key': 'api', 'title': 'Add the endpoint', 'verify': True},
           {'title': 'Document it', 'after': ['api']}])
t = dev.take()['task']['id']
dev.read('app.py')
dev.edit('app.py', [{'old': 'routes = []', 'new': 'routes = [health]'}])
dev.done(t, 'added /health; tests pass')
```

## CLI

`hive install|uninstall|doctor [harness]`, `hive start <harness> [prompt]`, `hive build [kind] [--list|--kinds]`, `hive ls`, `hive mount [name] [-- command]`, `hive unmount <name>`, `hive status`, `hive tree [agent] --depth 3`, `hive insights [query]`, `hive tail -f`, `hive history <agent>`, `hive summary [--agent a]`, `hive send <to> <body> --mode interrupt`, `hive tasks`, `hive plan plan.json`, `hive files`, `hive merges`, `hive run [--harness h]`, `hive faults`, `hive retry [task]`, `hive egregore [circles|circle|board|motions|charter|elders|calm|on|off]`, `hive host [--release]`, `hive upgrade [--now]`, and `hive hook <event>` for harnesses. Commands act on the hive of the current project, or the one `-H <name|number|path>` picks from `hive ls`. The CLI acts as an `operator` coordinator unless given `--as <agent>`.

## Configuration

`.hive/config.toml` holds the reminder interval, task retry limit, staleness threshold, tree limits (depth, fanout, root budget), insight automation and the global library path, summarizer settings, the runner's agent commands with their fallbacks, time limits, retry budgets, backoff, and rate-limit patience, and the egregore (`[egregore]`: automatic enrollment, circle size, terms, decay half-lives, rate limits). `HIVE_DB`, `HIVE_ROOT`, and `HIVE_SESSION` choose the hive; `HIVE_KEY` is the admin key for privileged roles over HTTP; `HIVE_AGENT` with `HIVE_ROLE`, or `HIVE_AGENT_TOKEN`, preset an agent's identity; `HIVE_LLM_API_KEY` (or `XAI_API_KEY`), `HIVE_LLM_BASE_URL`, `HIVE_LLM_MODEL`, and `HIVE_SUMMARIZER` control summaries.

## Development

```sh
uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest -q
```

`tests/e2e.py` runs Hive the way agents do, as separate processes over real transports: runner-launched agent processes that talk to `hive mcp` over stdio through the MCP config the runner writes (co-editing, verification, then the automatic compose and distill tasks, and a new agent recalling the saved insight), a shared tool served by one MCP process and called from another while it watches the server's live, window, and summary views, the HTTP server with its admin key, `hive hook` invoked as a subprocess with harness payloads, the CLI from `init` to `insights`, and several MCP processes editing one file at once. `e2e/live.py` drives real Grok agents (`grok` headless, sandboxed to a temporary workspace, with Hive as a project MCP server and hooks) through five scenarios and checks the resulting state: `coedit` (two agents edit one file concurrently and must settle a merge request between themselves), `hooks` (an agent edits with its own tools while the hooks sync its edits and deliver an interrupt), `runner` (a dependent plan with independent verification, every agent started by `hive run`, then one automatic composition once the whole plan has settled), `tree` (runner-launched researchers spawn their own runner child, then automatic compose and distill tasks produce a composition and a saved insight that a later session recalls), and `recover` (an agent whose turn limit is too small for its task keeps hitting it; Hive recognizes Grok's error, restarts the same agent with a brief each time, and the work completes without being redone). Run `python e2e/live.py [scenario ...] --model <model>`; it uses model credits, and results vary from run to run because the agents are real. Grok also starts every MCP server from your own Grok configuration in these workspaces, and on rare runs none of them connect in time for one agent; that agent then works without Hive's tools.

`tests/heal.py` drives scripted agents through every failure path: rate limits with provider wait hints, a fallback taking over, turn limits resumed with their progress, hung and overdue agents, authentication failures that pause a command until it is resumed, exhausted retries followed by `retry`, a runner that is stopped or killed, and a new runner adopting agents that are still working.

The suite covers composition and insight distillation, recursive spawning three levels deep through the runner, the merge algorithm (including agreement with `git merge-file`), co-editing and merge requests, task graphs and verification, messaging, summaries, the MCP server in process and over stdio, hooks, the runner, and several processes editing one file and racing for tasks.

## License

MIT