Status: shipped (v1). Every task in the #4907
task graph has landed: the scaffold, all four panes, the SSE stream and its
polling fallback, and every action (pause/resume, model apply, kick, ACMM
apply, local tmux attach). Per this record's own convention
(design/README.md), this page is not rewritten to describe
that delivery in detail — it stays the plan and the reasoning behind it, with
only the two corrections below and the
Delivery: hivectl tui note updated against what
actually shipped. src/docs/hivectl.md is the
operator reference and the page to read first — keybindings, pane cadence,
authorization failures, and v1 boundaries as delivered.
Two things in the epic's drafted text do not match this repository, and both
are corrected here with the evidence: the v2/ path prefix
(Paths) and the assumption that
dashboard/openapi.json is a usable contract for the action tasks
(Contract status).
Citations are against origin/v4 at 45a13d5.
Add a full-screen terminal UI to Hive that covers the day-to-day operator loop currently served by the web dashboard: watch the agent fleet, watch the governor, watch token spend, and take the common actions (pause/resume an agent, switch a model, apply an ACMM level, kick an agent now). Functional model is k9s — interactive, action-capable, keyboard-driven; visual inspiration is btop — dense live panes. This is not a second implementation of Hive logic: it is a second client of the existing dashboard API, consuming the same endpoints, the same auth token, and the same SSE stream as the web dashboard. Hive operators are terminal people by construction — agents live in tmux, the relay is a CLI, self-hosters are SSH'd into a box — so exposing :3001 or tunnelling it just to check governor mode is friction the web UI imposes. A second API consumer also hardens the contract: anything the TUI cannot do through the published spec is a gap worth an issue anyway, which is exactly what section 2.1 turned out to be.
Non-goals for v1, quoted from the epic:
- Hub-hosted hives / OAuth login flows. v1 targets self-hosted hives with the dashboard token. Hub auth is a follow-up epic.
- Remote terminal embedding via the ttyd WebSocket. v1 offers local tmux attach only (T22). Remote attach is a follow-up epic.
- Pixel parity with the web dashboard. Feature parity for the operator loop, not visual parity.
Quoted verbatim from #4907. These are settled; sub-issues should not relitigate them.
- Language/framework: Go,
charmbracelet/bubbletea+bubbles+lipgloss. Stays in-family with the existing Go module, and teatest gives us golden-file testing that runs in plain CI with no TTY.- Delivery: a subcommand of the existing binary (
hive tui) if the CLI entrypoint has subcommand structure; otherwise a siblingcmd/hive-tuimain in the same module. Task T1 resolves which.- Data source: the Node proxy on
:3001(auth + SSE live there), not the internal Go API on:3002. Base URL fromHIVE_DASHBOARD_URL(defaulthttp://localhost:3001), token fromHIVE_DASHBOARD_TOKEN.- Contract:
dashboard/openapi.jsonis the source of truth for every client task. If an operation the dashboard visibly performs is missing from the spec, the sub-issue's deliverable converts to filing a scoped follow-up issue describing the gap. That is a valid completion.- Testing: every task is verifiable with
go build ./...andgo test ./...alone. No task requires a running Hive stack, Docker, or network access. Client code tests againsthttptestfixture servers; rendering tests use teatest golden files.
Everything below this line is not part of the quoted decisions. It is what those decisions resolve to against this repository.
T1 resolves the open question in the Delivery decision. Of the two candidate entrypoints in the module, only one has subcommand structure:
hive(src/cmd/hive) is the spoke daemon, not a CLI. It parses a single-configflag, takes a process-wide singleton flock whose purpose is to refuse a secondhiveprocess (src/cmd/hive/main.go,singletonLockEnv), then runs the agent manager, dashboard and heartbeat for the container's lifetime. There is no subcommand dispatch to hangtuioff.hivectl(src/cmd/hivectl+src/pkg/hivectl/commands) is the operator-facing cobra CLI, and it already carries the plumbing the Data source decision specifies: its persistent--serverdefaults tohttp://127.0.0.1:3001and--token-envdefaults toHIVE_DASHBOARD_TOKEN(src/pkg/hivectl/commands/root.go).
So the command is hivectl tui.
Correction against delivery. This section originally proposed that the TUI
reuse hivectl's --server / --token-env flags for its base URL and token,
deviating from the Data source decision's HIVE_DASHBOARD_URL /
http://localhost:3001. That is not what shipped: newTUICommand
(src/pkg/hivectl/commands/tui.go) calls tui.Run() with nothing from
*commandEnv, so hivectl tui reads HIVE_DASHBOARD_URL and
HIVE_DASHBOARD_TOKEN directly — exactly the Data source decision as
written — and does not honour --server or --token-env. The two base
URL defaults consequently differ by one detail (http://localhost:3001 here
vs. http://127.0.0.1:3001 for --server's default on every other hivectl
command), which is worth knowing if you pass --server for a non-default host
elsewhere: the TUI will not pick it up. See
src/docs/hivectl.md for the
operator-facing version of this note.
The epic and its sub-issues specify v2/internal/tui/... and v2/docs/tui.md.
There is no v2/ directory in this repository and no module at the repo
root. The Go module is src/ (github.com/hivecommons/hive), which is where
go build ./... and every CI test shard run from
(.github/workflows/v2-tests.yml, working-directory: src). A tree at the repo
root would sit outside the module and never be compiled or tested at all.
The prefix is not a typo — it is a stale spelling. #3996 renamed the v2/
source tree to src/, recorded in src/pkg/reach/mapping.go:36-37:
#3996 renamed the v2/ source tree to src/, but a merged PR's file list isimmutable history: PRs merged before the rename report v2/... paths fromthe forge API forever
Within src/, code goes under pkg/ rather than internal/: every non-main
package in this module already lives there and the tree contains no internal/
directory, so internal/tui would introduce a second layout convention for one
package. The mapping for the whole epic:
| Epic spelling | This repository |
|---|---|
v2/internal/tui/app.go |
src/pkg/tui/app.go |
v2/internal/tui/client/ (T2, T4, T6, T8, T10, T13a) |
src/pkg/tui/client/ |
v2/internal/tui/panes/ (T3, T5, T7, T9, T11, T17, T19, T23) |
src/pkg/tui/panes/ |
v2/internal/tui/panes/testdata/ (golden files) |
src/pkg/tui/panes/testdata/ |
v2/docs/tui.md (T0) |
src/docs/design/tui.md — this page |
v2/docs/README.md (T26) |
src/docs/design/README.md |
Verification for every code task is go test ./pkg/tui/..., run from src/.
The Contract decision names dashboard/openapi.json as the source of truth and
tells a sub-issue what to do when an operation is missing from it. This section
records how large that gap actually is.
Originally measured at 45a13d5, the spec was GET-only: 32 routes, zero
writes. #5023 closed most of
that — it found the 32-vs-298 comparison had been made against
dashboard/server.js, a legacy Node prototype that dashboard/README.md
states v2 production never starts, and re-measured against the live Go server.
Current state:
| Method | Published in dashboard/openapi.json |
|---|---|
Distinct /api paths |
255 |
GET |
131 |
POST |
83 |
PUT |
64 |
DELETE |
14 |
The Phase 2 action tasks now have a contract to build against, and the two read
tasks that were blocked are unblocked: /api/agents is in the spec (get,
post), as is /api/acmm/evaluation and /api/events.
The Phase 2 action endpoints are all published — note the path parameter is
{agent}, not {name}: POST /api/pause/{agent}, POST /api/resume/{agent},
POST /api/kick/{agent}, plus /api/agents/{name}/kicks.
One endpoint remains unpublished by design. GET /api/health (used by
hivectl system health, commands/system.go) sits in the parity test's
documented exception set as "not part of the client data contract", alongside
/api/health/deep, /api/livez, /api/docs, /api/contribute/ws,
/api/terminal/assertion/renew and the legacy /api/v1/ catch-all. T2 should
treat it as a deliberate exception rather than a gap to fill.
TestOpenAPISpecCoversEveryRegisteredRoute
(src/pkg/dashboard/openapi_route_parity_test.go, added by #5023) now fails if
a registered route and the spec diverge in either direction, so this section
should not go stale again silently.
What this means for sub-issues. The epic's own escape hatch applies and
should be used deliberately rather than as a surprise: a task whose endpoint is
absent should file the scoped spec-gap issue and build against the endpoint
hivectl already calls, citing this table — not stall. The alternative reading,
that a missing spec entry blocks the task, would block six of them at once and
leave the TUI read-only. Widening dashboard/openapi.json to cover the write
surface is worth its own issue; it is not something any single pane task should
absorb.
Header bar, a 2×2 pane grid, and a footer keybinding strip. The sketch is the target for T3 (grid) and T5/T7/T9/T11 (pane contents); it is not a golden file.
┌──────────────────────────────────────────────────────────────────────────────┐
│ hive: acme-prod governor: ●BUSY ws: connected 12:04:31 │
├───────────────────────────────────────┬──────────────────────────────────────┤
│ AGENTS [1] │ GOVERNOR [2] │
│ NAME STATE BACKEND │ mode BUSY │
│ ▸scanner running claude │ queue depth 7 actionable │
│ quality running copilot │ next eval in 3m12s │
│ reviewer paused claude │ eval interval 5m │
│ ux-discovery idle codex │ budget 41% of daily │
│ │ acmm level L4 │
├───────────────────────────────────────┼──────────────────────────────────────┤
│ TOKENS [3] │ EVENTS [4] │
│ AGENT IN OUT COST │ 12:04:02 kick scanner (governor) │
│ scanner 1.2M 88.1k $4.10 │ 12:03:41 pr #4919 opened │
│ quality 410.3k 31.0k $1.32 │ 12:01:58 quality → idle │
│ reviewer 96.7k 12.4k $0.38 │ 11:58:20 reviewer paused (operator)│
│ ───────────────────────────────── │ 11:57:03 bead bd-1042 closed │
│ total 1.7M 131.5k $5.80 │ 11:55:44 governor QUIET → BUSY │
├───────────────────────────────────────┴──────────────────────────────────────┤
│tab focus p pause m model A acmm K kick a attach H hives ? help q quit│
└──────────────────────────────────────────────────────────────────────────────┘
Notes the sketch encodes, for the tasks that implement it:
- Header carries hive name, a governor mode badge, and connection state. Connection state is its own field because the SSE stream can drop while the process stays up (T13b); a TUI that silently shows stale numbers is worse than one that says it is disconnected.
- Focus is shown two ways — the
[n]pane index and the▸row cursor — because only one pane has focus but every pane keeps its own selection. - Numbers are illustrative. No pane task should treat these as expected
output; the golden files in each pane's
testdata/are the assertion. - T24 owns the below-minimum-size path: at small terminals the grid is not shrunk, it is replaced by a single message.
| Key | Action | Scope | Task |
|---|---|---|---|
tab / shift+tab |
Cycle pane focus forward / backward | global | T3 |
j / k, ↓ / ↑ |
Move the selection within the focused pane | focused pane | T3, T11 |
p |
Pause or resume the selected agent | Agents pane | T15 |
m |
Open the model picker for the selected agent | Agents pane | T17 |
K |
Kick the selected agent now | Agents pane | T21 |
A |
Open the ACMM level overlay | global | T19 |
a |
Attach to the selected agent's tmux session (local only) | Agents pane | T22 |
H |
Open the Hives overlay: the contributor profiles this machine can lend a CLI to, with enter to switch, a add, d remove, r rename |
global | #8128 |
? |
Toggle the help overlay | global | T23 |
q / ctrl+c |
Quit | global | T1 |
Conventions these bindings assume:
- Case is meaningful.
Kkicks andAopens ACMM, whilekmoves the cursor up andaattaches. The destructive-ish member of each pair is the shifted one, deliberately:kis pressed constantly during navigation and must never be one missed shift away from an action. - Actions apply to the selection in the focused pane, never to a global "current agent". A key that acts on an agent while the Agents pane is not focused should be a no-op, not a guess.
- Confirmation is per-risk, not uniform. T15 specifies a confirm modal for pause/resume and T19 specifies typed confirmation for an ACMM change, because an ACMM level applies fleet-wide and is not obviously reversible from the same screen.
qquits from the top level only once overlays exist; an open overlay should consume it (T23).- One overlay is not about this hive.
Hlists the hives the MACHINE can lend a CLI to — the contributor profiles in~/.config/hive/profiles.yml, not anything the dashboard API knows about — so it is global rather than addressed at a pane, and it reads and writes throughpkg/hivectl, the same functionshivectl hivesuses. It is also the only overlay with text fields: while one is composing, ordinary letters are characters, not bindings.
Every task is verifiable with go build ./... and go test ./... alone — no
running Hive, no Docker, no network.
-
Client code (
src/pkg/tui/client/) tests againsthttptestfixture servers. Fixtures are captured response bodies, not live calls. -
Rendering (
src/pkg/tui/panes/) uses teatest golden files undersrc/pkg/tui/panes/testdata/, regenerated with:cd src && go test ./pkg/tui/panes/... -update-updateis registered bygithub.com/charmbracelet/x/exp/golden(golden.go:15), whichteatest.RequireEqualOutputcalls; it is not a flag this repository defines. Regenerated files must be reviewed in the diff like any other change — a golden file updated without reading it asserts nothing. -
Behaviour that is not layout — key handling, quit, focus movement — should be asserted directly rather than through a golden file, so that a deliberate layout change does not force an unrelated behavioural test to be regenerated. The scaffold's
TestAppQuitsis the pattern: it drives the model through teatest so the assertion coverstea.Quitactually reaching the program, not merely being returned. -
Golden files are terminal output. They contain escape sequences and are width-sensitive, so every golden test must pin its size with
teatest.WithInitialTermSize; a test that inherits a default size will produce a diff on someone else's machine.
- #4907 — the tracker, task table, and filing protocol.
hivectl— the non-interactive client for the same API, and the command this TUI is a subcommand of.api-reference.md— the dashboard API as documented for humans; see section 2.1 for how much of itdashboard/openapi.jsonactually publishes.