vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
atlas 43e69d345e subagents, ACP: stop with SIGINT only, so claude ends its own tool commands 
claude's Bash tool starts every command in a new session, so a signal to
claude's process group never reaches it. claude stops those commands
itself when SIGINT makes it shut down. A SIGKILL leaves them running,
re-parented to init. Per the ruling on #4999, every stop is SIGINT and
nothing escalates.

- Subagent `interrupt` always sends SIGINT. The `force` argument is gone
  from the MCP tool and from `session::interrupt`. A caller that still
  sends `force: true` gets SIGINT; the argument is ignored.
- `interrupt` used to free the session name before it signalled, so a
  `continue` could start a second claude on the session while the first
  was still exiting. The `running` map now holds a three-state `Slot`
  (starting, running, stopping). An interrupted claude turn is
  `Stopping` until the turn task's own `finish_turn` clears it. `status`
  says "stopping", and `start`/`continue` on that name are refused.
  `interrupt` still returns at once. The ACP arm is unchanged: its name
  is freed when `session/cancel` is sent.
- ACP `Connection` drop sends its process group SIGINT, not SIGKILL, and
  the spawn no longer sets tokio's `kill_on_drop`, which SIGKILLed the
  leader after the `Drop` body. The test fixture's background grandchild
  resets SIGINT to default, since `&` starts it ignored.

Tests: a fake claude that records SIGINT, interrupted, fails with
`cancel(true)` (the old `force: true` path). An interrupted fake claude
that keeps running keeps its name claimed and `continue` is refused,
which fails when the slot is freed before the signal. A fake ACP agent
that records SIGINT, dropped, fails with SIGKILL in `Drop`, and also with
SIGINT in `Drop` but `kill_on_drop(true)` left in place.

Not changed: hive-claude's idle watchdog (still SIGKILL, separate
hive-claude change), the units' `KillSignal`, `machinectl kill`, and the
login helper.
2026-10-11 02:44:31 +02:00
..
agent-lifecycle hive-c0re: close build-log rows a dead process left in flight 2026-10-11 02:37:08 +02:00
crates check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00
getting-started hive telemetry collector: fetch its OIDC secret from the store under the hive's own leaf 2026-10-10 01:10:31 +02:00
integrations docs/integrations: title the forge and matrix pages as swarm-level 2026-10-10 14:06:43 +02:00
networking hive CA: delete ca.pem, ca-previous.pem and ca-key.pem, the bundle is the store's root 2026-10-05 21:17:10 +02:00
process agents: persistent /agents/<n>/work dir outside state/ 2026-10-05 12:56:02 +02:00
scheduler hive telemetry collector: keep the secret wait for an operator-named file 2026-10-10 01:16:04 +02:00
swarm docs/review-classifier: cost comes from OTEL labels, not the swarm UI 2026-10-10 19:30:25 +02:00
tools subagents, ACP: stop with SIGINT only, so claude ends its own tool commands 2026-10-11 02:44:31 +02:00
trust-boundary container stats: measure agent disk usage through hive-priv, unknown on failure 2026-10-05 18:56:46 +02:00
turn-loop agent-modules: hand an api-key agent's subagent daemon the backend file 2026-10-10 01:05:50 +02:00
web-ui claude runtime: interrupting a session kills every process it started 2026-10-11 02:44:31 +02:00
README.md docs: make review classifier page generic over swarms 2026-10-10 18:54:02 +02:00

README.md

hyperhive docs

Depth reference for hyperhive — the substrate, not the pitch (that's the top-level README / website). Every page here stands alone; pick the one matching your task rather than reading top to bottom. For the autogenerated NixOS options reference (every services.hyperhive.* / hyperhive.* option, host and agent), see the options site instead — this tree is prose, that one's generated straight from the module declarations.

Getting started

  • Bringing a fresh swarm online? → getting-started/setup.md (the hand steps after the first switch).
  • What does the dashboard look like, and how do I use it? → web-ui/ — the operator-facing starting point; its own sub-pages (shape, dashboard, agent, css-vars, terminal-rendering) go deeper into implementation.
  • What tools does an agent (or the operator) have available? → tools/ — hivectl (yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix).

Agent lifecycle

Trust boundary & security

Accounts & integrations

  • How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → integrations/forge.md (the swarm's Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
  • How does the matrix-tuwunel container work? Multiple accounts per agent? → integrations/matrix.md (the homeserver); tools/matrix.md for the MCP tool surface and services.hyperhive.agent.matrixAccounts.
  • How do I give an agent a GitHub account (gh + git push)? how's the PAT injected? → integrations/github.md (operator content up top; the gh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom).
  • What's /knowledge? How does the swarm-wide knowledge repo sync, and how do I contribute a document? → integrations/knowledge.md.
  • What does hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); tools/hivectl-cli.md for the exhaustive, autogenerated flag reference.

Networking & swarms

  • What nginx vhosts does the gateway serve? How does matrix discovery work? → networking/gateway.md.
  • How does DNS resolution work in agent containers? What's the bridge network for? → networking/network.md.
  • How do I connect two hives into a swarm? → swarm/ (peer hives, TLS trust).
  • Where do agent snapshots go? How does the swarm's btrfs receive endpoint authenticate a pushing hive? → networking/snapshot-store.md.
  • Who mints each credential, who reads it, and how does it rotate — and where's that shape headed? → swarm/credentials.md (current state, target state, and the progressive-enhancement rule); swarm/secrets.md for where each file lives today.
  • How does the secret store come up, who writes its grants, how's it sealed? → swarm/bao.md.
  • How does an agent get a prompt at set times, and why doesn't it fire twice after downtime? → swarm/schedules.md.
  • How do I set an agent's model or effort from the swarm, and what happens to its own pick? → swarm/inference.md.
  • How will a PR get checked against its repo's own yes/no rules before a full review? → swarm/review-classifier.md (planned, not implemented yet).

Scheduler, CI, observability

  • what's the job queue, as a general idea (not hive-c0re specifics)? → scheduler/jobq.md — operator-facing, no implementation detail.
  • How does the rebuild queue work? What are the concrete step kinds, queue sources, scheduler internals? → scheduler/coordinator.md.
  • How does the CI runner work? How does it register? → scheduler/ci.md.
  • How do I export Claude Code metrics (tokens, cost, tool calls) to Prometheus/Grafana? → scheduler/observability.md.

Crate reference

  • What does a specific Rust crate do, on its own terms? → crates/ — every workspace crate's own README.md, one level up from source; the crate itself is still the source of truth, this is just a walkable mirror.

Process & conventions