pi-hive

A globally-installed extension for Pi, the coding agent by Earendil Works. pi-hive runs a hierarchical team of agents (a "hive") on a project: an Orchestrator delegates to team Leads, each Lead fans work out to its Members, each agent runs as its own pi subprocess with scoped tools and enforced filesystem domains, and a status view shows the live tree.

Note: This is a Pi host extension, not a standalone Node library — it is loaded by Pi via pi.extensions, not imported directly.

The /hive-observe dashboard: live session topology (orchestrator → leads → members), per-session KPIs, streaming activity, cost, and model mix.

What this is

Most agent frameworks hand you a fixed swarm and a black box. pi-hive is the opposite: it's config-first, and you own the whole tree. Nothing runs until you describe the team.

• Config-first — you own everything. The extension does nothing until a project contains .pi/hive/hive-config.yaml. That one file is both the opt-in trigger and the team definition: you declare the agents, their models, their tools, their filesystem domains, and their nesting. Roles aren't magic — a node is a lead if it has members and a member if it doesn't, and an agent may delegate only to its own direct reports. You express permissions by nesting, not by writing policy. Every agent's prompt, knowledge, and skills live as plain files under .pi/hive/ in your repo, versioned with your code. See SETUP.md for the full authoring guide.

• A real hierarchy, not a flat swarm. The visible session is an orchestrator that routes but never edits. It delegates to team leads, each lead fans work out to its members, and each agent runs as its own isolated pi subprocess with a scoped tool allow-list and enforced write domains — a worker physically cannot edit files outside the scope its lead granted it. Nesting goes arbitrarily deep.

• Plan first, then execute — two separate teams. The session runs in one of three modes (normal → plan → hive, cycled with Ctrl+Alt+T). Plan mode activates a planning: team that produces a full spec and writes no code. Hive mode activates a separate hive: team that executes an already-approved spec. They're distinct trees in your config so a project can never silently run planning against its coding tree.

• Spec-driven, backed by OpenSpec. Non-trivial work flows through fixed gates — proposal → requirements → design → tasks — stored under .pi/hive/plans/<change-id>/. OpenSpec (a CLI dependency) is the store and validator: it owns the artifact dependency graph and reports per-artifact readiness. Execution is hard-gated — /hive-execute refuses to run until tasks.md exists and its gate is approved.

• Human-in-the-loop plan review, self-hosted. pi-hive embeds a Plannotator review surface directly in its own dashboard — no per-review server. You annotate, approve, or deny each plan artifact in the browser; approval unblocks the planner, a denial routes your feedback back and holds the gate. Verdicts persist to local SQLite.

• Local, private telemetry. Every session streams its own tailored event log to .pi/hive/sessions/, and /hive-observe opens a local Solid + Vite dashboard (127.0.0.1:43191) showing live topology, delegation lifecycle, tokens, and cost across every project and session. Nothing is sent to any third party.

Install location & activation

Install from GitHub with pi install (recommended):

pi install git:github.com/demetere/pi-hive          # latest main
pi install git:github.com/demetere/[email protected]   # pin a tag/commit

pi install also accepts the full HTTPS or SSH URL, e.g. pi install https://github.com/demetere/pi-hive or pi install ssh://[email protected]/demetere/pi-hive. Pi runs npm install for the package, so the extension's runtime dependency (OpenSpec) is fetched automatically; the Pi host packages are declared as peer dependencies and provided by Pi at load time.

You can also add it declaratively in Pi's settings.json:

{
  "packages": ["git:github.com/demetere/pi-hive"]
}

For local development, load a checkout temporarily without installing:

pi -e .        # from the repository root

When installed, Pi auto-discovers the package for every project.

For repository-first development, use just as the command source of truth:

just pi-dev         # run this checkout temporarily with pi -e .
just pi-reload-dry-run # preview copying this checkout to ~/.pi/agent/extensions/pi-hive
just pi-reload         # update the user-level extension from this checkout

After just pi-reload, run /reload in Pi.

• Activates only when a project contains .pi/hive/hive-config.yaml. Without it, the extension registers nothing — no tools, no commands, no hooks — so non-hive projects are completely unaffected.

Quickstart

1. Install the extension (see above), so Pi discovers it for every project.
2. In the project you want to run a hive on, create .pi/hive/hive-config.yaml. This file is the opt-in trigger and defines the team tree — the fastest way to author it is to point an agent at SETUP.md and let it interview you (see Build a hive in a new project below).
3. Start Pi in that project and press Ctrl+Alt+T (or run /hive) to enter hive mode; the visible session becomes a Lead that delegates to its team.
4. Run /hive-observe to open the live telemetry dashboard at http://127.0.0.1:43191.

/hive-doctor runs read-only diagnostics if anything looks off.

Requirements

• Bun ≥ 1.1 — the telemetry dashboard server (src/observability/server/index.ts) runs under Bun and uses bun:sqlite. The /hive-observe command notifies you if Bun is missing.
• The Pi host provides @earendil-works/pi-coding-agent and @earendil-works/pi-tui at load time (declared as peer deps).

Packaging & distribution

This extension is self-contained and ships in two ways:

• Git — clone or submodule into ~/.pi/agent/extensions/. The prebuilt dashboard (ui/web/dist/) is committed, so there is no build step at install time. Dependency folders are gitignored.
• Tarball/package — just pack-dry-run previews the published package contents. The root package.json files allowlist ships only runtime code + the prebuilt dist/; dependency folders never ship. The package prepack hook delegates to just prepack, so a published package can never contain stale UI.

After editing anything under ui/web/src/, rebuild the committed bundle:

just dashboard-build   # Vite build + stamp dist/.build-hash

Guard against shipping stale UI (wire into a pre-commit hook or CI):

just dashboard-verify  # fails if dist/ is out of date with src/

Build a hive in a new project

Point an agent at the build guide and let it interview you:

"Set up a hive for this project. Follow ~/.pi/agent/extensions/pi-hive/SETUP.md — interview me for the teams, members, domains, and models, then scaffold .pi/hive/."

SETUP.md is the authoritative, self-contained playbook: the config + frontmatter schema, copy-paste templates for orchestrator/lead/member, the interview questions, conventions (tools, domains, distiller), and a validation checklist.

Modes and commands (only registered when a hive is configured)

pi-hive has three hardcoded session modes: normal → plan → hive → normal. The cycle order is not configurable.

• normal — plain Pi chat. No hive tools or hive enforcement.
• plan — the planning: team is active. The visible main session should be agent-type: planner; plan gates run in order proposal → requirements → design → tasks under .pi/hive/plans/<change-id>/.
• hive — the hive: team is active. The visible main session should be agent-type: lead; execution agents build an approved tasks.md.

Commands:

• /hive-normal, /hive-plan-mode, /hive — switch to a specific mode.
• /hive-toggle or Ctrl+Alt+T — cycle normal → plan → hive → normal.
• /hive-execute <change-id> — validates that the change exists, has tasks.md, and the tasks gate is approved, then switches to hive mode and drives execution.
• /hive-plan [change-id] — list plan changes or select/show one.
• /hive-status — open the live hierarchy view (per-agent status, tokens, cost).
• /hive-doctor — run read-only diagnostics for opt-in config, loaded agents, dashboard assets, Bun availability, SDD state, and telemetry paths.
• /hive-observe — restart/open the local browser dashboard for global hive telemetry (http://127.0.0.1:43191 by default).
• /hive-observe-stop — stop the telemetry dashboard on the configured port.

The hive tool set is mode/type scoped in code, not configurable by users: plan mode exposes planning/store/review tools to eligible planners/reviewers, hive mode exposes delegation/status/review tools to eligible execution agents, and normal mode exposes none. The dashboard host/port default to 127.0.0.1:43191 and can only be changed with HIVE_TELEMETRY_HOST / HIVE_TELEMETRY_PORT.

SDD/OpenSpec is the default operating mode for non-trivial hive work. Agent skills: paths are passed to worker Pi processes explicitly with --no-skills plus repeated --skill <path>, so Hive reuses Pi's native skill system without automatic discovery bleed-through.

Layout of a configured project

.pi/hive/
  hive-config.yaml      # the team tree + global settings (also the activation trigger)
  agents/               # one folder per agent, mirroring the tree; each holds <name>.md + <name>-mental-model.yaml
  knowledge/            # always-inlined context/reference files
  skills/               # Pi Agent Skills explicitly granted to agents
  sessions/             # runtime transcripts + hive-events.jsonl telemetry (gitignore this)

See SETUP.md §4 for the full directory contract.

Hive telemetry

pi-hive writes its own tailored telemetry stream to .pi/hive/sessions/<session>/hive-events.jsonl for each hive session and a live mutable state snapshot to .pi/hive/sessions/<session>/hive-state.json. Top-level sessions are also registered in a global index at ~/.pi/agent/hive/telemetry-sessions.jsonl, so one /hive-observe dashboard can show hives from multiple projects and many simultaneously running sessions.

/hive-observe starts a local Bun/SSE dashboard with hive-specific views for project/session cards, topology, delegation lifecycle, worker state, tool activity, tokens, and cost. The dashboard also indexes events/state into local SQLite at ~/.pi/agent/hive/telemetry.db for fast reloads and historical browsing. Telemetry persists even when the dashboard is not running; serve it only when you want to watch or inspect.

The dashboard UI is a prebuilt Solid + Vite single-page app under ui/web/. The server (src/observability/server/index.ts) serves the built bundle from ui/web/dist/, which is committed so end users need no build step. If you change anything under ui/web/src/, rebuild it:

just dashboard-install # first time only
just dashboard-build   # rebuild dist/ — the server picks it up on next page load

Before publishing or opening a release PR, run the same gates as CI:

just ci

During UI development you can run just dashboard-dev (Vite HMR on port 43192) with a telemetry server running on HIVE_TELEMETRY_PORT; the dev server proxies the /events, /states, /stream, and /health endpoints to it.

This is not wired to a third-party observability server. Runtime knobs are hive-specific:

• HIVE_TELEMETRY_PORT — dashboard port, default 43191
• HIVE_TELEMETRY_HOST — dashboard host, default 127.0.0.1
• HIVE_TELEMETRY_NO_OPEN=1 — start the server without opening a browser
• HIVE_TELEMETRY_REGISTRY — override the global session registry path
• HIVE_TELEMETRY_DB — override the local SQLite database path