hyperhive/CLAUDE.md

hyperhive — claude entry point

Hey claude. This is your starting page. The detailed docs live in 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.
• 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 (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.
• Odd-looking nspawn / container plumbing usually has a story: 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.

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.
• 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.
• swarmctl/ — swarm operator CLI; runs as root and acts directly (README says why). Does not link swarm-controller — its wire shapes 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.
• 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.
• 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-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. Design: 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.
• 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.
• swarm-review-classifier/ — one claude --print per PR classification, no tools, no forge credential. Design: 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,ruth}.nix (container entry points), 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 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.
• 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.