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 + scratchpad.

• High-level project intro: README.md.
• Open work + backlog: TODO.md.

File map

hive-c0re/         host daemon + CLI (one binary, subcommand-dispatched)
  src/main.rs           clap setup; serve / spawn / kill / rebuild / list /
                         pending / approve / deny / destroy [--purge] /
                         request-spawn; periodic vacuum tasks
  src/server.rs         host admin socket (HostRequest → dispatch)
  src/client.rs         admin-socket client
  src/manager_server.rs manager-privileged socket (ManagerRequest)
  src/agent_server.rs   per-sub-agent socket listener (long-poll Recv)
  src/broker.rs         sqlite Message store + broadcast channel for SSE +
                         hourly vacuum of delivered>30d
  src/approvals.rs      sqlite Approval queue + kinds
  src/operator_questions.rs  sqlite question queue backing `ask_operator`
  src/events_vacuum.rs  host-side hourly sweep of every agent's
                         /state/hyperhive-events.sqlite
  src/crash_watch.rs    poll every 10s; fire HelperEvent::ContainerCrash
                         when a previously-running container disappears
                         without an operator-initiated transient
  src/coordinator.rs    shared state (broker/approvals/questions/transient/
                         sockets) + tombstone enumeration + kick_agent
  src/actions.rs        approve/deny/destroy (transient-aware)
  src/auto_update.rs    startup rebuild scan + ensure_manager +
                         meta::lock_update_hyperhive bump
  src/lifecycle.rs      `nixos-container` shellouts; per-agent applied
                         + proposed git repo seeding; tag plumbing
  src/meta.rs           single hive-c0re-owned flake at /var/lib/
                         hyperhive/meta/ — sync_agents, two-phase
                         prepare/finalize/abort, lock_update_*
  src/migrate.rs        startup auto-migration from pre-meta layout
                         (idempotent, marker-guarded phase 4)
  src/dashboard.rs      axum HTTP: static shell + /api/state JSON + actions
                         + journald viewer + bind-with-retry (SO_REUSEADDR)
                         + deployed_sha chip per container
  assets/               index.html, dashboard.css, app.js (include_str!)

hive-ag3nt/        in-container harness crate; produces TWO binaries
  src/lib.rs            re-exports + DEFAULT_SOCKET, DEFAULT_WEB_PORT
  src/client.rs         generic JSON-line request/response over unix socket
  src/web_ui.rs         per-container axum HTTP page (incl /api/cancel,
                         /api/compact, /api/model, /events/history)
  src/events.rs         LiveEvent + broadcast Bus + sqlite-backed history
                         (/state/hyperhive-events.sqlite) + TurnState +
                         model selection (persisted at /state/hyperhive-model)
  src/turn.rs           claude --print + stream-json pump; --compact retry
  src/mcp.rs            embedded MCP server (rmcp): AgentServer + ManagerServer
  src/login.rs          probe /root/.claude/ for a valid session
  src/login_session.rs  drives `claude auth login` over stdio pipes
  src/bin/hive-ag3nt.rs sub-agent main (Serve + Mcp subcommands)
  src/bin/hive-m1nd.rs  manager main (Serve + Mcp subcommands)
  assets/               index.html, agent.css, app.js (include_str!)
  prompts/              static role/tools/settings for claude (include_str!):
                          agent.md  — sub-agent system prompt
                          manager.md — manager system prompt
                          claude-settings.json — --settings JSON

hive-sh4re/        wire types (HostRequest/Response, AgentRequest/Response,
                   ManagerRequest/Response, Message, Approval, HelperEvent)

nix/
  modules/hive-c0re.nix         systemd service + firewall + git wiring
  templates/harness-base.nix    shared scaffolding for sub-agents + manager
  templates/agent-base.nix      sub-agent nixosConfiguration
  templates/manager.nix         manager nixosConfiguration

docs/
  conventions.md       naming, identity=socket, async forms, commit style
  gotchas.md           NixOS / nspawn lessons learned the hard way
  web-ui.md            dashboard + per-agent page layouts and endpoints
  turn-loop.md         claude invocation, wake prompt, MCP tool surface
  approvals.md         approval flow, manager policy, helper events
  persistence.md       sqlite dbs, retention, state dir layout

Reading paths

Pick the doc that matches your task. None depend on the others — read them à la carte.

• "What does the dashboard look like?" → docs/web-ui.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.

Quick reminders

• Commit before test. Stage and commit when work looks ready, then run validation. Failures get a follow-up commit rather than an amend.
• Commit messages: short, lowercase, no Co-Authored-By trailer. Imperative mood.
• rebuild is the reconcile verb. Anything that changes per-container state on the host should be re-applied there so the dashboard's ↻ R3BU1LD is sufficient to recover.
• Identity = socket. No auth tokens — the socket path identifies the principal.
• Actions are factored between admin socket and dashboard via actions.rs and dashboard.rs::lifecycle_action, so the two surfaces never drift.

Scratchpad

In-flight or recent context that hasn't earned a section yet. Prune freely.

• Just landed: meta-flake overhaul. Each agent's applied repo is a tiny module-only flake (nixosModules.default = import ./agent.nix); agent.nix is a plain NixOS module function — no extendModules, no hyperhive input visible to the manager. A single hive-c0re-owned repo at /var/lib/hyperhive/meta/ declares one input per agent (pointing at that agent's applied repo via git+file://) and one nixosConfigurations.<n> output per agent, wrapping inputs.agent-<n>.nixosModules.default with the identity + HIVE_PORT / HIVE_LABEL / HIVE_DASHBOARD_PORT injection. Containers run against meta#<n>. Every approve runs nix flake lock --update-input agent-<n> (two-phase: prepare on the build path, finalize/abort on the result) — meta's git log is the system-wide deploy audit trail; failures and denials live as annotated tags in applied. The manager has /applied and /meta RO-bound and the applied remote pre-wired in every proposed repo so git fetch applied, git show applied/refs/tags/deployed/<id>, git -C /meta log --oneline, cat /meta/flake.lock all just work. Migration runs idempotently on hive-c0re startup (HIVE_SKIP_META_MIGRATION=1 skips it): rewrites pre-meta applied flakes to module-only, wires the proposed remote, seeds meta, and repoints every container at meta#<n> (guarded by a marker so the expensive phase only runs once).
• Just landed (prior overhaul still underneath): tag- driven config-apply. Two-repo split (proposed = manager RW, applied = core-only); request_apply_commit fetches the manager's commit into applied and pins it as proposal/<id>; approve / deny / build walk through tags on the same commit; applied/main only fast- forwards on deployed/. failed/ + denied/ are annotated. See docs/approvals.md.
• Recent (since last compaction): inline +/- diffs on Write/Edit, send full body via collapsed details, operator cancel + ttl on questions, deny-with-reason, dashboard back-link + last-turn timing + model chip, per-agent inbox view, bind-retry + SO_REUSEADDR, journald viewer, agent.nix viewer, server-side TurnState, recv(wait_seconds) max 180s, runtime /model switch + persistence to /state, crash watcher + ContainerCrash / NeedsLogin / LoggedIn / NeedsUpdate events, manager update tool, pure-hash agent_web_port + collision banner + spawn/rebuild preflight, browser notifications, focus-preserving refresh, generalised
  survival, prompt-on-submit pattern.
• Open threads: custom per-agent MCP tools (groundwork for moving bitburner-agent into hyperhive), two-step spawn, per-agent send allow-list, telemetry/charts, notes compaction, unprivileged containers, Bash allow-list, xterm.js. Known bug (in TODO.md): question id=5 was queued but didn't render — likely a pending() row-decode error swallowed by unwrap_or_default; investigate by curl /api/state | jq '.questions' + browser console.