Terminal dashboard (colibri-tui)
Terminal dashboard (colibri-tui)
← index
The TUI is Colibri's live terminal dashboard. It connects to the daemon's Unix
socket, pulls the GlasspaneSnapshot, and renders a color-coded table of
supervised panes. It is a display client, not part of the daemon, and not
the same thing as colibri-glasspane.
Why it is not colibri-glasspane
colibri-glasspane is the state machine that decides what state an agent
is in from its JSONL events. colibri-tui is the screen that asks the
daemon "what does the radar look like right now?" and draws it.
| Artifact | Role | Resident crate |
|---|---|---|
colibri-glasspane | Pane state machine, event ingestor, snapshot builder | crates/colibri-glasspane |
colibri-tui | Terminal dashboard client with rows, colors, keybindings | crates/colibri-glasspane-tui (binary = colibri-tui) |
The split matters because the daemon, the MCP bridge, the CLI, and tests all
use colibri-glasspane. The TUI is just one consumer. If the TUI is not
installed, or crashes, agents keep running.
Decisions
Keep the daemon separate from any terminal UI
colibri-tui is a standalone process. It resolves the daemon socket the same
way the CLI does (DaemonConfig::from_env().socket_path), then calls
client.glasspane_snapshot() every two seconds. The daemon has no awareness of
crossterm or ratatui.
This is the same "service owns state, clients render it" pattern as the MCP
bridge and the CLI. It keeps Colibri headless-safe, which is required for an
rc.d service that must boot before any operator logs in.
→ crates/colibri-glasspane-tui/src/main.rs (socket resolution, refresh loop)
TUI gets spawn/kill keys, not just read-only status
You can spawn a local test agent (s) and kill the selected pane (x) from
the dashboard. That overlaps with commands the colibri CLI can already do,
but the experience is different: a CLI command is one-shot; the TUI is a live
supervision surface with a selected row and an immediate status bar.
We kept the action keys because the dashboard's job is to let an operator
notice and react — spot a stalled pane and kill it without leaving the
terminal.
→ crates/colibri-glasspane-tui/src/main.rs (spawn_agent, kill_selected)
One taxonomy from one snapshot
The TUI does not parse agent stdout. It only reads the already-folded
GlasspaneSnapshot, so Pi, zot, and local test agents are rendered with the
same columns, colors, and state icons. The rendering code concerns itself only
with layout and keybindings; all semantic decisions live in
colibri-glasspane.
→ crates/colibri-glasspane/src/lib.rs (AgentState, GlasspaneSnapshot)
Naming: the binary is colibri-tui, the crate is colibri-glasspane-tui
The crate directory is colibri-glasspane-tui because the package implements
"a TUI for the glasspane." The installed binary is named colibri-tui
because that is what an operator types. CLAWDIE-STUDIO-PROPOSAL.md and other
docs refer to colibri-tui as shorthand; there is no separate colibri-tui
crate.
This duality is currently accepted. If we ever add a second TUI surface (e.g.
a colibri-tui-web or colibri-tui-gui), the naming becomes confusing and
should be revisited.
Current keybindings
| Key | Action |
|---|---|
q / Esc | Quit, or close detail pane if open |
r | Refresh snapshot now |
s | Spawn a local colibri-test-agent |
x | Kill the selected pane |
Enter | Open/close the detail pane for the selected row |
Tab / Shift-Tab | Cycle through distinct sessions |
j / k or ↓ / ↑ | Navigate the pane table |
When to use the TUI vs the CLI
Use the TUI when:
- You want a live, auto-refreshing view of all panes.
- You are picking a pane to inspect or kill visually.
- You are on an SSH session with only a terminal.
Use the colibri CLI when:
- You are scripting or piping output (
colibri snapshot | jq). - You need a command not bound to a key (e.g.
claim-task,set-cost-mode). - You want a one-shot answer without entering an alternate screen.
See also
- glasspane — the pane state machine the TUI renders
- operator-cli — the
colibriCLI that shares the same socket client