hyperhive/AGENTS.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/2-handbook/hives/boundary.md](docs/2-handbook/hives/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/2-handbook/agents/security.md](docs/2-handbook/agents/security.md)**.
- Odd-looking nspawn / container plumbing usually has a story:
  **[docs/5-project/process/gotchas.md](docs/5-project/process/gotchas.md)**.

## Build & check

Always through the devshell — a bare `cargo` fails (`failed to find tool
"cc"`, `cannot find -lsqlite3`). Details:
[`docs/5-project/process/conventions.md`](docs/5-project/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/2-handbook/hives/hivectl-cli.md`
(same for `swarmctl` → `docs/2-handbook/swarm/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, 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/2-handbook/hives/hivectl-cli.md`](docs/2-handbook/hives/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/2-handbook/hives/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.
- **`hive-meta-flake/`** — the meta flake's `flake.nix` text, a pure
  render, and the reads of its pins. swarm-controller renders and reads
  with it; hive-c0re reads none of its pins.

Wire types + socket plumbing:

- **`hive-types/`** — leaf newtypes, chiefly the validated `Ident`.
- **`hive-template/`** — the one template language (minijinja, strict undefined): `render`, `variables`.
- **`hive-sh4re/`** — shared payload types (`Message`, …).
- **`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,
  `AGENTS.md` edits, agent create and forge-token, inference, limits and
  permissions).
- **`swarmctl/`** — swarm operator CLI; runs as **root and acts directly**
  (README says why). Doesn't link `swarm-controller`: every body it sends
  or reads comes from `swarm-controller-api`. ⚠️ 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/2-handbook/swarm/swarmctl-cli.md`](docs/2-handbook/swarm/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.
  Feature `otel` adds `cert_metrics`, the `bao.client_cert.*` gauges.
- **`swarm-queue-client/`** — the one authenticated connect to the swarm
  NATS queue.
- **`swarm-wire/`** — serde-only request and reply contracts services
  exchange over the queue (builder, claude login, review classifier, agent inference, login, permissions and terminal streams), so naming one links
  neither the queue client nor the store client.
- **`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/`** — client-server API calls against the swarm
  homeserver, shared by `swarm-controller`, `swarm-matrix-ctl`, `hive-c0re`
  and `hive-matrix-mcp`.
- **`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,
  builds each agent from `internal/meta` before its deploy, and evaluates the
  agent archetypes the create form lists.
  Design: [`docs/4-implementation/swarm/builder.md`](docs/4-implementation/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/4-implementation/swarm/ci-metrics.md`](docs/4-implementation/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/4-implementation/swarm/claude-login.md`](docs/4-implementation/swarm/claude-login.md).
- **`swarm-notify-router/`** — forge events from swarm-controller's
  webhooks to todos on the agents they concern, through each agent's own
  consumer on the `ROUTER_TODOS` stream. Design:
  [`docs/4-implementation/swarm/notify-router.md`](docs/4-implementation/swarm/notify-router.md).
- **`swarm-review-classifier/`** — one `claude --print` per PR
  classification, no tools, no forge credential. Design:
  [`docs/4-implementation/swarm/review-classifier.md`](docs/4-implementation/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), and
  `examples/`, the NixOS files the handbook's worked examples use. CI
  evaluates them.
- **`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/5-project/process/conventions.md`](docs/5-project/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 implementation detail mixed in**: a section
  of source paths, wire formats or build internals belongs on a page under
  `docs/4-implementation/`, with a short pointer left in the handbook page
  (see how `docs/2-handbook/swarm/forge.md` points to
  `docs/4-implementation/agent-tools/forge-notify.md`). A short aside that
  an operator may want but most do not goes in a
  `<details><summary>…</summary>` block (blank line after `<summary>` so the
  markdown inside renders), as in `docs/2-handbook/swarm/schedules.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.