hyperhive/README.md

hyperhive

Multi-Claude-Code-agent orchestration on nixos-containers.

A host-side Rust daemon (hive-c0re) spawns nspawn-isolated agent containers and brokers messages between them. A manager agent (hm1nd) coordinates the swarm and gates lifecycle changes on user approval via git commits, surfaced through a vibec0re-styled HTTP dashboard.

                     ┌────────────────────────┐
                     │  hive-c0re (Rust)      │
        operator ──▶ │  • lifecycle           │ ─▶ nixos-containers
                     │  • broker (sqlite)     │     ├── hm1nd       (manager)
                     │  • approvals (sqlite)  │     ├── h-alice     (sub-agent)
                     │  • dashboard :7000     │     └── h-bob       ...
                     │  • per-agent sockets   │
                     └────────────────────────┘

Each container runs a harness binary that drives claude --print --continue in a turn loop, exposes a per-agent web UI with a live event stream, and talks to the broker over a bind-mounted unix socket via an embedded MCP server claude calls into.

Read next

• CLAUDE.md — developer reference: conventions, gotchas, per-subsystem design, file map.
• TODO.md — open work items.

Build / deploy

# inside the repo (devshell first; no global cargo)
nix develop -c cargo check
nix develop -c cargo clippy --workspace --all-targets -- -D warnings

# evaluate everything (rust+nix+toml fmt + clippy)
nix flake check

# deploy to a host that imports `hyperhive.nixosModules.hive-c0re`
cd ~/Repos/<nixos-config-repo>
nix flake update --update-input hyperhive
sudo nixos-rebuild switch --flake .#<host>

The host config also needs hyperhive.overlays.default applied — the module's default package = pkgs.hyperhive requires the overlay.