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). src/main.rs is the hive-c0re binary — daemon-only (serve + the periodic vacuum/sweep loops); the operator CLI lives in the separate hivectl crate, which talks to the daemon over the host admin socket. 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.
hivectl/ — standalone operator CLI (hivectl binary). Talks to the hive-c0re daemon over the host admin socket (hive-host-sock wire types) — does NOT link hive-c0re. Verbs: agents <spawn|kill| destroy|rebuild|restart|list|set-parent|…>, approvals <pending| approve|deny>, forge/matrix/github/gateway provisioning, choom, stop/start, wg/peer-config.
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.
"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 (index: the loop, binary shape, turn outcomes; sub-pages: claude-invocation, config, mcp).
"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 do I give an agent a GitHub account (gh + git push)? How is the PAT injected?" → docs/github.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.
"How do I export Claude Code metrics (tokens, cost, tool calls) to a Prometheus/Grafana collector? What OTEL options are available?" → 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.
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.
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

8.3 KiB Raw Blame History