hyperhive/CLAUDE.md

# hyperhive — claude entry point

Hey claude. This is your starting page. The detailed docs live in
[`docs/`](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](README.md)**.
- Open work + backlog: **[TODO.md](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`](docs/web-ui.md).
- **"How does claude get its prompt and what tools does it have?"** →
  [`docs/turn-loop.md`](docs/turn-loop.md).
- **"How do config changes flow from manager to operator to
  container?"** → [`docs/approvals.md`](docs/approvals.md).
- **"What state survives destroy / purge / restart?"** →
  [`docs/persistence.md`](docs/persistence.md).
- **"Naming, commit style, wire protocol, the `data-async`
  pattern."** → [`docs/conventions.md`](docs/conventions.md).
- **"Why does the nspawn flag look like that?"** →
  [`docs/gotchas.md`](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 module-only flake (forwards every `inputs.*`
  through to `agent.nix` as the `flakeInputs` module arg —
  manager edits `inputs` to pull in external flakes like an
  MCP server's own flake; the new sha lands in the agent's
  own `flake.lock` and rolls up to meta's). A single
  hive-c0re-owned repo at `/var/lib/hyperhive/meta/`
  declares one input per agent and one
  `nixosConfigurations.<n>` output, wrapping the agent's
  `nixosModules.default` with identity + `HIVE_PORT` /
  `HIVE_LABEL` / `HIVE_DASHBOARD_PORT` /
  `HIVE_OPERATOR_PRONOUNS`. Containers run against
  `meta#<n>`. Every approve uses two-phase staging
  (prepare → build → finalize/abort) so meta's git log only
  records successful deploys; failures + denials live as
  annotated tags in applied. All meta operations
  serialize behind a tokio mutex; stale `.git/index.lock`
  is cleared on hive-c0re startup. Manager has `/applied`
  + `/meta` RO-bound + the `applied` remote pre-wired in
  every proposed repo. Migration runs idempotently on
  startup (`HIVE_SKIP_META_MIGRATION=1` skips). Operator
  pronouns are a NixOS module option
  (`services.hive-c0re.operatorPronouns`, default
  `"she/her"`); the harness substitutes them into the
  system prompt at boot.
- **Just landed:** per-agent extra MCP servers via the
  `hyperhive.extraMcpServers.<key>` NixOS option in
  `agent.nix`. Declares `{ command, args, env,
  allowedTools }`; the module writes the whole map to
  `/etc/hyperhive/extra-mcp.json`; the harness reads that
  file and merges each entry into both `--mcp-config`
  and `--allowedTools` (mapped to `mcp__<key>__<pattern>`).
  Unblocks matrix / bitburner / any agent with rich
  domain tooling — the agent flake's `inputs` block pulls
  the external flake, `agent.nix` references it via
  `flakeInputs.<name>.packages.${pkgs.system}.default`.
- **Just landed:** `mcp__hyperhive__ask_operator` is now on
  the sub-agent surface too (not just the manager). Answer
  routes back to whichever agent asked via
  `coord.notify_agent`; the dashboard already shows the
  asker on each question row.
- **Just landed:** dashboard now has a terminal-style
  compose textbox under the message-flow stream — `@name`
  picks the recipient (sticky in localStorage, auto-
  completed from `containers[]`), POSTs `/op-send`. New
  per-agent `↻ new session` button drops `--continue` for
  one turn. Claude spawns with `cwd = /state` so relative
  paths in tool calls land in the durable dir.
- **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
  <details data-restore-key> 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.