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 at
  **`$HIVE_FORGE_URL/hyperhive/hyperhive/issues`**. Read the host out of
  the env var — inside an agent container `localhost` is the *agent*, not
  the forge, so a hardcoded loopback address fails to connect.
- Operator/agent trust-boundary design:
  **[docs/trust-boundary/boundary.md](docs/trust-boundary/boundary.md)** (`area/ops` issues
  for the deployment/gateway/privsep work — the separator is a **slash**,
  and `--label area:ops` now fails with `did you mean "area/ops"?`).
- Agent trust model (trust boundary, prompt-injection threat model,
  capability = accepted risk), credential isolation + sandbox threat model:
  **[docs/trust-boundary/security.md](docs/trust-boundary/security.md)**.
- Odd-looking nspawn / container plumbing usually has a story:
  **[docs/process/gotchas.md](docs/process/gotchas.md)**.

## Build & check

Always through the devshell — a bare `cargo` fails (`failed to find tool
"cc"`, `cannot find -lsqlite3`). Details:
[`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).

```sh
nix develop -c cargo clippy --all-targets -- -D warnings
nix develop -c cargo test
nix fmt        # treefmt is the CI gate, NOT bare cargo fmt
```

Changed a `hivectl` / `swarmctl` verb or flag? Regenerate its doc — only
CI's `nix flake check` catches the drift:
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md`
(same for `swarmctl` → `docs/tools/swarmctl-cli.md`). CI red but local
green → build the suspect check (e.g. `nix build
.#checks.x86_64-linux.hivectl-docs`) before blaming the builder.

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

Per-hive (host + in-container):

- **`hive-c0re/`** — host daemon (runs as the unprivileged `hive-core`
  user), **daemon-only** — the operator CLI is `hivectl`. Owns the sqlite
  broker, reminder queue, meta flake, lifecycle (`nixos-container`
  shellouts), gateway wiring, per-container stats and the axum operator
  dashboard. Agent forge/matrix accounts are `swarm-controller`'s. Largest
  crate.
- **`hivectl/`** — operator CLI; talks to `hive-c0re` over the host admin
  socket, does NOT link it. Verb reference (CI-enforced):
  [`docs/tools/hivectl-cli.md`](docs/tools/hivectl-cli.md).
- **`hive-priv/`** — minimal root helper, socket-activated at
  `/run/hive/priv.sock`; the few root ops (bind-mount edits, nsenter)
  `hive-c0re` delegates. See `docs/trust-boundary/boundary.md`.
- **`hive-agent/`** — the in-container serve loop: turn-loop *policy*
  (`turn.rs`) over `hive-runtime`, per-agent web UI, event + turn-stats
  sinks, system-prompt renderer, claude launch config (`mcp_config.rs`).
  With `hive-agent-mcp` it's what "hive-ag3nt" refers to — there is no
  such directory.
- **`hive-agent-mcp/`** — the embedded MCP server (`hive-mcp-http` unit).
- **`hive-runtime/`** — the `Runtime` interface an agent's turns run on:
  a `claude` backend (over `hive-claude`) and an `acp` backend whose stream
  is translated into claude's `stream-json` shape. Links no hyperhive
  binary crate, so the subagent daemon uses it too.
- **`hive-bash-mcp/`**, **`hive-matrix-mcp/`**, **`hive-subagent-mcp/`** —
  per-agent MCP daemons serving streamable-http directly (no stdio
  bridge): background bash tasks, matrix-sdk tools, nested subagent
  sessions (optionally goal-driven over several turns; daemon state is
  in-memory, the claude session survives a restart).
- **`hive-screen-mcp/`** — stdio MCP bridge for GUI agents: screenshot,
  keyboard, mouse. All userspace.
- **`hive-forge/`** — `hive-forge` Forgejo CLI; one module per verb.
- **`hive-forge-notify/`** — notification pollers → todos on the in-agent
  socket. Two binaries: `hive-forge-notify`, `hive-github-notify`.
- **`hive-jobq/`** — the job-DAG scheduler library. **Runtime-only —
  nothing writes the graph to disk**, so node ids are stable within a run,
  not across restarts. `hive-c0re`'s `job_queue/` is being removed in its
  favour — new scheduler-shaped code goes here.
- **`hive-jobq-wire/`** — presentation of a `hive-jobq` graph to viewers
  (`WireNode` / `WireResource`); kept out of `hive-jobq` on purpose.
- **`hive-jobq-metrics/`** — OTEL export of a graph's state rollup on a
  timer.
- **`hive-log/`** — the one log-sink chooser: journald *or* stdout, never
  both (under a unit, stdout already is the journal). Do not grow it into a
  utility crate.
- **`hive-metric/`** — one-shot CLI pushing a labeled metric over OTLP.

Wire types + socket plumbing:

- **`hive-types/`** — leaf newtypes, chiefly the validated `Ident`.
- **`hive-sh4re/`** — shared payload types (`Message`, `HelperEvent`, …).
- **`hive-host-sock/`** (hivectl ↔ c0re), **`hive-priv-sock/`** (c0re ↔
  priv), **`hive-core-agent-sock/`** (harness ↔ c0re, `/run/hive/mcp.sock`)
  — per-socket wire types, split out so each client links only its protocol.
- **`hive-agent-sock/`** — the *in-agent* socket the harness serves to
  in-container producers (todos, reminders); also holds the `extra_mcp`
  spec. ⚠️ **This socket never leaves the container** — `hive-c0re` is not
  in the path, unlike `hive-core-agent-sock`.
- **`hive-sock-client/`** — the shared JSON-line unix-socket client; retry
  is a policy value (`Retry::None` / `Retry::RideOutRestart`). Also holds
  the bounded request-line reader (`read_request_line`) the socket servers
  use.

Swarm-level:

- **`swarm-controller/`** — owns what is true **across** hives; opt-in,
  one per swarm. Serves HTTP over a unix socket nginx proxies to — ⚠️
  **the socket's directory is its access control**; the crate README has
  the constraint and a unit test pins the path.
- **`swarm-controller-api/`** — serde-only request and response bodies of
  the controller's HTTP API, shared with `swarmctl` (forge, schedules and
  the agent-create and forge-token responses).
- **`swarmctl/`** — swarm operator CLI; runs as **root and acts directly**
  (README says why). Doesn't link `swarm-controller`: the forge and
  schedule bodies and the agent responses come from
  `swarm-controller-api`; the agent-create request, inference and
  permissions ones are a local mirror. ⚠️ Edits authelia's
  **`users.yml` in place**, shared with `swarm-authelia-bridge`; that
  crate's README says what both writers must uphold. Verb reference
  (CI-enforced):
  [`docs/tools/swarmctl-cli.md`](docs/tools/swarmctl-cli.md).
- **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire
  types) — the other writer of authelia's users DB; runs inside
  `swarm-authelia`.
- **`swarm-secret-client/`** — OpenBao client over `vaultrs`. ⚠️ Reads
  the **`BAO_`** env spellings explicitly — `vaultrs`'s `VAULT_*` defaults
  are set by no unit here, and falling through to them yields a client
  with **no identity** and a TLS failure that names no cause.
- **`swarm-queue-client/`** — the one authenticated connect to the swarm
  NATS queue.
- **`swarm-nats-auth/`** — NATS auth-callout responder; without it the
  queue is fail-closed and admits nobody.
- **`swarm-agent-verify/`** — checks a `swarm-agent.<agent>.<secret>`
  token against the store; shared by `swarm-nats-auth` and
  `swarm-logs-auth`.
- **`swarm-logs-auth/`** — nginx `auth_request` responder for agent access
  to the log store, and to the metrics store as `swarm-metrics-agent-auth`.
- **`swarm-metrics-auth/`** — nginx `auth_request` responder for Grafana's
  bearer on the metrics store's query API.
- **`swarm-logs/`** — agent CLI: a LogsQL query in, log lines out.
- **`swarm-metrics/`** — agent CLI: a MetricsQL query in, the store's JSON out.
- **`swarm-matrix-client/`** — appservice calls against the swarm
  homeserver, shared by `swarm-controller` and `swarm-matrix-ctl`.
- **`swarm-matrix-ctl/`** — the one binary run inside
  `containers.hive-matrix`; new in-container jobs are verbs here, not
  crates.
- **`swarm-builder/`** — builds agent config PR heads for commit status,
  and evaluates the agent archetypes the create form lists.
  Design: [`docs/swarm/builder.md`](docs/swarm/builder.md).
- **`swarm-ci-metrics/`** — polls the forge's Actions runs and pushes each
  finished run's duration and queue wait to the metrics store. Design:
  [`docs/swarm/ci-metrics.md`](docs/swarm/ci-metrics.md).
- **`swarm-claude-login/`** — runs `claude auth login` for one agent and
  stores the credentials at `swarm/agents/<agent>/claude-credentials`.
  Design: [`docs/swarm/claude-login.md`](docs/swarm/claude-login.md).
- **`swarm-review-classifier/`** — one `claude --print` per PR
  classification, no tools, no forge credential. Design:
  [`docs/swarm/review-classifier.md`](docs/swarm/review-classifier.md).

### External dependencies with no directory here

- **`hive-claude`** — app-agnostic driver for headless `claude --print`
  (stream-json, `Telemetry`, the self-compacting `InfiniteSession`).
  ⚠️ **Its own repo, not a workspace member** — there is no
  `hive-claude/` directory and `grep` here will not find it.

### Other top-level dirs

- **`frontend/`** — npm workspaces built hermetically by
  `nix/packages/frontend.nix`: `shared`, `dashboard` (operator SPA),
  `agent` (per-container UI), `swarm-ui` (Preact; packaged separately by
  `nix/packages/swarm-ui.nix`, not in `packages.default`'s closure).
- **`nix/`** — `host-modules/` (the host stack), `agent-modules/`
  (per-agent harness features), `container-modules/` (guest side of
  service containers), `templates/agent.nix` (the container entry
  point), `archetypes/` (the built-in agent archetypes), `packages/`,
  `docs/` (options doc), `module-eval/` (NixOS
  module-eval tests), `builder/` (`check-flake`), `script-tests/`, 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

**[`docs/README.md`](docs/README.md) is the single index**, grouped by
topic. Don't add a second copy of it here — a parallel list used to live
in this file and drifted.

## Conventions & process

- **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a
  helper, add backticks, etc.). Worked examples:
  [`docs/process/conventions.md`](docs/process/conventions.md#building--local-checks).
- **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`
- **Comment/PR-description length**: size it to how non-obvious the
  thing is, not to how much investigation it took to find it — a
  mechanical fix gets a one-line comment, a genuinely non-obvious
  invariant or decision earns real prose. Don't restate a module's `//!`
  doc in a comment further down the same file.
- **Operator-facing doc with real implementation detail mixed in**: wrap
  the implementation part in a `<details><summary>…</summary>` block
  (blank line after `<summary>` so the markdown inside renders) rather
  than a sibling page — see `docs/integrations/github.md`'s
  "Implementation" section. It only collapses in a rendered browser, and
  the `<summary>` line isn't markdown-processed, so keep it plain prose
  with no backticks.