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.
• Operator/agent trust-boundary design: 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.

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; one hive binary for every agent. Turn loop (turn.rs), embedded MCP server (mcp.rs), per-agent web UI (web_ui.rs), event + turn-stats sqlite sinks, login flow, system-prompt renderer, forge-notify subscriber.
• 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/frontend.nix. Packages: shared (terminal pane + Catppuccin palette), dashboard (the operator SPA), agent (the default per-container UI).
• nix/ — NixOS modules (modules/hive-{c0re,forge,gateway,matrix, ci,network}.nix) + per-container templates (templates/{harness-base, agent-base,manager,weston-vnc}.nix) + the options-doc derivation.
• 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.
• "What does the dashboard look like?" → docs/web-ui.md (index; sub-pages: shape, dashboard, agent).
• "How does the per-agent terminal classify + colour events?" → docs/terminal-rendering.md.
• "How does claude get its prompt and what tools does it have?" → docs/turn-loop.md.
• "How do config changes flow from manager to operator to container?" → docs/approvals.md.
• "What state survives destroy / purge / restart?" → docs/persistence.md.
• "Naming, commit style, wire protocol, the data-async pattern." → docs/conventions.md.
• "Why does the nspawn flag look like that?" → docs/gotchas.md.
• "What nginx vhosts does the gateway serve? How does matrix discovery work?" → docs/gateway.md.
• "How do per-agent forge accounts work? What does forge_notify poll + how does it format wake messages?" → docs/forge.md.
• "What verbs does hive-forge support? How do I post a comment, upload an attachment, manage subscriptions?" → 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.
• "How does the matrix-tuwunel container work? What about fluffychat-web and per-agent matrix accounts?" → docs/matrix.md.
• "How does DNS resolution work in agent containers? What's the bridge network for?" → 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.
• "How does the rebuild queue work? What are queue kinds and sources?" → docs/coordinator.md.
• "How does the CI runner work? What's the auto-registration flow?" → docs/ci.md.
• "What is /knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document?" → docs/knowledge.md.

Conventions & process

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

• Commit style, naming, identity, reconcile verb: → docs/conventions.md.
• NixOS / nspawn quirks (bind mounts, conf flags, etc.): → docs/gotchas.md.
• Turn loop, sentinels (rate-limit, auth-failed), context window: → docs/turn-loop.md.
• Two-step spawn, approval flow, flake.lock validation: → docs/approvals.md.