# 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/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/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.` output, wrapping the agent's `nixosModules.default` with identity + `HIVE_PORT` / `HIVE_LABEL` / `HIVE_DASHBOARD_PORT` / `HIVE_OPERATOR_PRONOUNS`. Containers run against `meta#`. 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.` 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____`). 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..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/`; 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.