hyperhive/CLAUDE.md

# hyperhive — claude entry point

Hey claude. This is your starting page. The detailed docs live in
[`docs/`](docs/) and are written for humans + you both — read them
when you need depth on a subsystem. This file is the index.

- High-level project intro: **[README.md](README.md)**.
- Open work + backlog: the **[forge issue
  tracker](http://localhost:3000/hyperhive/hyperhive/issues)**.
- Operator/agent trust-boundary design:
  **[docs/boundary.md](docs/boundary.md)** (`area:ops` issues
  for the deployment/gateway/privsep work).
- Agent trust model (trust boundary, prompt-injection threat model,
  capability = accepted risk), credential isolation + sandbox threat model:
  **[docs/security.md](docs/security.md)**.

## Repo map

One line per crate / top-level dir. **Each module's authoritative,
always-current description lives in its own `//!` doc-comment** —
`grep`/read the module when you need detail. This index is kept
deliberately lean: it auto-loads into every turn's context, and a
hand-maintained per-file tree drifts out of sync with the code.

### Rust workspace (`Cargo.toml` members)

- **`hive-c0re/`** — host daemon (runs as the unprivileged `hive-core`
  user) plus two operator CLIs. `src/main.rs` is the `hive-c0re` binary
  (serve / spawn / kill / rebuild / approve / destroy / periodic vacuum
  loops); `src/bin/hivectl.rs` is the ad-hoc operator admin CLI. Owns
  the sqlite broker, approval + question + reminder + schedule queues,
  the meta flake, lifecycle (`nixos-container` shellouts), gateway /
  forge / matrix provisioning, per-container stats, and the axum
  operator dashboard (`dashboard.rs`). Largest crate.
- **`hive-ag3nt/`** — in-container harness; three sibling binaries for
  every agent (`hive-agent` serve loop, `hive-agent-mcp`,
  `hive-agent-wake`). Turn-loop *policy* layer (`turn.rs`) over the `hive-claude`
  driver, embedded MCP server (`mcp.rs`) + its claude launch-config layer
  (`mcp_config.rs`: tool-group/capability → `--allowedTools`, `--mcp-config`
  render), per-agent web UI (`web_ui/` module dir), event + turn-stats
  sqlite sinks, login flow, system-prompt renderer, forge-notify subscriber.
- **`hive-claude/`** — reusable, app-agnostic driver for headless
  `claude --print`: spawns the CLI, streams + classifies stream-json,
  parses per-turn `Telemetry`, and drives a durable self-compacting
  `InfiniteSession` (name + `SessionStore` + `CompactionPolicy`). Uses
  `thiserror` (it's a library); the `hive-*` binaries consume it with
  `anyhow`. See `hive-claude/README.md`.
- **`hive-priv/`** — minimal root privileged-helper, socket-activated at
  `/run/hive/priv.sock`; performs the few root operations (bind-mount
  edits, nsenter) the unprivileged `hive-c0re` delegates to it. See
  `docs/boundary.md`.
- **`hive-forge/`** — `hive-forge` Forgejo CLI wrapper; one module per
  verb under `src/verbs/`.
- **`hive-matrix-mcp/`** — per-agent matrix-sdk daemon plus the thin
  stdio MCP bridge claude spawns per turn.
- **`hive-bash-mcp/`** — per-agent bash-task runner daemon plus its
  stdio MCP bridge; writes task files under `/harness/bash-tasks/` and
  the favorite-tools `bash_commands` stat into turn-stats.sqlite.
- **`hive-sh4re/`** — shared wire types (Host / Agent / Manager request
  + response, `Message`, `Approval`, `HelperEvent`) used across the
  unix sockets.

### Other top-level dirs

- **`frontend/`** — npm workspaces → static dashboard + per-agent UI
  dist, built hermetically by `nix/packages/frontend.nix`. Packages:
  `shared` (terminal pane + Catppuccin palette), `dashboard` (the
  operator SPA), `agent` (the default per-container UI).
- **`nix/`** — `host-modules/` (the host stack: hyperhive core options,
  `hive-{c0re,priv,forge,gateway,matrix,network,tls,ci}`, otel, swarm),
  `agent-modules/` (the per-agent harness feature modules),
  `templates/{agent,ruth}.nix` (container entry points), `packages/`
  (flake package outputs), `docs/` (the options-doc derivation), plus
  `sources.nix` / `rust.nix` / `checks.nix` / `devshell.nix` /
  `treefmt.nix` behind the thin `flake.nix`.
- **`docs/`** — subsystem reference docs (see *Reading paths* below).
- **`branding/`**, **`scripts/`** — static assets + helper scripts.

## Reading paths

Pick the doc that matches your task. None depend on the others —
read them à la carte.

- **"How do I bring a fresh hive online (first-run hivectl
  bootstrap)?"** → [`docs/setup.md`](docs/setup.md).
- **"What does the dashboard look like?"** →
  [`docs/web-ui.md`](docs/web-ui.md) (index; sub-pages:
  [`shape`](docs/web-ui/shape.md),
  [`dashboard`](docs/web-ui/dashboard.md),
  [`agent`](docs/web-ui/agent.md)).
- **"How does the per-agent terminal classify + colour
  events?"** → [`docs/terminal-rendering.md`](docs/terminal-rendering.md).
- **"How does claude get its prompt and what tools does it have?"** →
  [`docs/turn-loop.md`](docs/turn-loop.md) (index: the loop, binary shape,
  turn outcomes; sub-pages:
  [`claude-invocation`](docs/turn-loop/claude-invocation.md),
  [`config`](docs/turn-loop/config.md), [`mcp`](docs/turn-loop/mcp.md)).
- **"How do config changes flow from manager to operator to
  container?"** → [`docs/approvals.md`](docs/approvals.md).
- **"What state survives destroy / purge / restart?"** →
  [`docs/persistence.md`](docs/persistence.md).
- **"Naming, commit style, wire protocol, the `data-async`
  pattern."** → [`docs/conventions.md`](docs/conventions.md).
- **"Why does the nspawn flag look like that?"** →
  [`docs/gotchas.md`](docs/gotchas.md).
- **"What nginx vhosts does the gateway serve? How does matrix
  discovery work?"** → [`docs/gateway.md`](docs/gateway.md).
- **"How do per-agent forge accounts work? What does forge_notify
  poll + how does it format wake messages?"** →
  [`docs/forge.md`](docs/forge.md).
- **"What verbs does `hive-forge` support? How do I post a comment,
  upload an attachment, manage subscriptions?"** →
  [`docs/tools/forge.md`](docs/tools/forge.md).
- **"What does `hivectl` do? How do I provision a forge/matrix account,
  manage gateway users, restart containers, or drop into an agent shell?"** →
  [`docs/tools/hivectl.md`](docs/tools/hivectl.md).
- **"How does the matrix-tuwunel container work? What about
  fluffychat-web and per-agent matrix accounts?"** →
  [`docs/matrix.md`](docs/matrix.md).
- **"How do I give an agent a GitHub account (`gh` + `git push`)?
  How is the PAT injected?"** → [`docs/github.md`](docs/github.md).
- **"How does DNS resolution work in agent containers? What's the
  bridge network for?"** → [`docs/network.md`](docs/network.md).
- **"How do I connect two hives into a swarm? How do I declare peer
  hives and configure TLS trust?"** →
  [`docs/swarm.md`](docs/swarm.md).
- **"How does the rebuild queue work? What are queue kinds and sources?"** →
  [`docs/coordinator.md`](docs/coordinator.md).
- **"How does the CI runner work? What's the auto-registration flow?"** →
  [`docs/ci.md`](docs/ci.md).
- **"What is `/knowledge`? How does the hive-wide knowledge repo sync,
  and how do I contribute a document?"** →
  [`docs/knowledge.md`](docs/knowledge.md).
- **"How do I export Claude Code metrics (tokens, cost, tool calls) to
  a Prometheus/Grafana collector? What OTEL options are available?"** →
  [`docs/observability.md`](docs/observability.md).

## Conventions & process

The docs below own the details — this section just points at them.

- **Commit style, naming, identity, reconcile verb:** →
  [`docs/conventions.md`](docs/conventions.md).
- **NixOS / nspawn quirks** (bind mounts, conf flags, etc.): →
  [`docs/gotchas.md`](docs/gotchas.md).
- **Turn loop, sentinels (rate-limit, auth-failed), context
  window:** → [`docs/turn-loop.md`](docs/turn-loop.md).
- **Two-step spawn, approval flow, flake.lock validation:** →
  [`docs/approvals.md`](docs/approvals.md).
- **Pre-push lint hook** (catches tracker-tag and comment-block failures
  before CI does — install once per clone):
  `ln -sf ../../scripts/pre-push .git/hooks/pre-push`