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).

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 + intra-process broadcast
                         channel (`MessageEvent`) for `recv_blocking_batch` +
                         the dashboard forwarder; hourly vacuum of acked>30d
  src/dashboard_events.rs unified wire-facing event channel feeding
                         `/dashboard/stream`. Carries broker `Sent` /
                         `Delivered` (mirrored by the forwarder task
                         in main.rs) + mutation events
                         (`ApprovalAdded` / `ApprovalResolved`,
                         `QuestionAdded` / `QuestionResolved`,
                         `TransientSet` / `TransientCleared`). Each
                         frame carries a monotonic per-process `seq`
                         clients use to dedupe against snapshot reads.
  src/approvals.rs      sqlite Approval queue + kinds
  src/operator_questions.rs  sqlite question queue backing `ask` /
                         `answer` (both operator + agent-to-agent)
  src/questions.rs      shared dispatch for `Ask` / `Answer` —
                         used by both agent + manager surfaces
  src/reminder_scheduler.rs  5s poll loop: drains due reminders,
                         resolves file_path container→host, persists
                         payload + delivers pointer string
  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/container_view.rs ContainerView struct + build_all helper;
                         shared between dashboard.rs (cold-load via
                         /api/state) and coordinator.rs's
                         rescan_containers_and_emit
  src/coordinator.rs    shared state (broker/approvals/operator_questions/
                         transient/sockets) + tombstone enumeration +
                         kick_agent + notify_agent (helper-event push) +
                         last_containers cache + rescan_and_emit diff helper
  src/loose_ends.rs     loose-ends aggregator (pending approvals +
                         unanswered questions + pending reminders) —
                         for_agent (filtered) and hive_wide (manager
                         surface). Backs AgentRequest::GetLooseEnds +
                         ManagerRequest::GetLooseEnds (the
                         get_loose_ends MCP tool).
  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/forge.rs          optional Forgejo wiring: per-agent users +
                         tokens, the `agent-configs` org, and
                         `push_config` — mirrors each applied repo
                         into `agent-configs/<n>` on the local forge
  src/dashboard.rs      axum HTTP: static shell + /api/state JSON + actions
                         + journald viewer + bind-with-retry (SO_REUSEADDR)
                         + deployed_sha chip per container +
                         /dashboard/{stream,history} subscribing to the
                         unified DashboardEvent channel
  assets/               index.html, dashboard.css, app.js (include_str!)

hive-fr0nt/           shared frontend-assets crate (browser only).
  src/lib.rs            pub const BASE_CSS / TERMINAL_CSS / TERMINAL_JS /
                         MARKED_JS re-exports; both binaries
                         `include_str!` them and prepend to their per-
                         page serving routes.
  assets/base.css       Catppuccin palette + body typography (one source
                         of truth, no per-page redeclaration).
  assets/terminal.css   `.terminal-wrap` + `.live` + `.tail-pill` +
                         `.row` / `details.row` styling for both
                         pages' lit log panes. Unified prefix-column
                         (padding-left + negative text-indent) so glyph
                         alignment is consistent across row kinds + a
                         `.md` block scope for marked-rendered bodies.
  assets/terminal.js    `window.HiveTerminal.create(opts)`: scroll-
                         sticky log + "↓ N new" pill + history
                         backfill + SSE subscribe-buffer-snapshot-
                         dedupe dance. Pages register a kind→renderer
                         map; the terminal owns the lifecycle.
  assets/marked.min.js  vendored marked v4.0.2 UMD bundle. Per-agent
                         terminal uses the global `marked.parse` for
                         markdown bodies on send / recv / ask / answer
                         / assistant text rows.

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,
                         /screen, /screen/ws)
  src/turn_stats.rs     per-turn analytics sink (one sqlite row per
                         turn at /state/hyperhive-turn-stats.sqlite);
                         schema + best-effort writer
  src/stats.rs          read-side aggregations over turn-stats.sqlite
                         backing the /stats page (bucketed Snapshot:
                         turns / duration / tokens / model mix)
  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;
                         proactive compaction + auto session-reset
  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, stats.html,
                         stats.js, screen.html (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;
                                 imports hive-forge.nix
  modules/hive-forge.nix        optional in-container Forgejo
                                 (`hyperhive.forge.enable`, default on);
                                 Catppuccin Mocha theme via tmpfiles C+ copy
  templates/harness-base.nix    shared scaffolding for sub-agents + manager
  templates/agent-base.nix      sub-agent nixosConfiguration
  templates/manager.nix         manager nixosConfiguration
  templates/weston-vnc.nix      optional `hyperhive.gui.enable`
                                 — weston + VNC backend systemd unit; writes
                                 /etc/hyperhive/gui.json (vnc_port + auth) for
                                 the harness WebSocket relay (/screen/ws)
  forge-theme/theme-catppuccin-vibec0re.css  Catppuccin Mocha forge theme

docs/
  conventions.md       naming, identity=socket, async forms, commit style
  gotchas.md           NixOS / nspawn quirks and lessons learned
  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
  terminal-rendering.md  per-agent terminal row taxonomy (as built)
  boundary.md          operator/agent trust model rationale
  damocles-migration.md  future migration plan for damocles → hyperhive

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

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.
• Two-step spawn: request_init_config → edit agent.nix → request_spawn. Never submit a Spawn approval without first reviewing the config template.
• Rate-limit sentinel: {state_dir}/hyperhive-rate-limited is written by the harness on 429 and cleared on retry. ContainerView.rate_limited reads it for the dashboard badge.