Skip to content

Product Book TUI

Grzegorz Nowak edited this page Oct 12, 2026 · 7 revisions

TUI & Observability

Part of the Product Book. Observable product behaviour at pi-schematic @ 36bd569 (main, 2026-10-12).

Pi is a terminal coding agent; pi-schematic is an extension that adds session tooling to it. Most of that tooling is felt through Pi's terminal interface (its TUI): a status bar reporting the state of the session, slash commands that open small overlays, and a live view of any child agent the parent delegates to. This chapter covers the status bar and its pressure cues, the commands and overlays, live rendering of a spawned child, inline tool output, and how the interface stays safe and responsive under load. The behaviour rows behind the prose are collected verbatim in the appendix.

1. The status bar: context, memory, topic, and posture

The status bar is the operator's instrument panel. Its most prominent reading is context usage — how much of the model's working window the session occupies. When Pi reports a valid percentage the bar shows it rounded as ctx N%; when that figure is unavailable or malformed it shows ctx --% rather than a misleading number.

Context pressure is communicated by colour as well as number. Below 30% the reading is green and dim; from 30% through 49% it is yellow/accent; from 50% through 69% it is orange/warning; and at 70% or more it is red/error. The colour makes the transition visible early, while a raw token counter can still look comfortable.

Three smaller indicators round out the bar. The notebook appears as 📒 N when nonempty and stays discoverable as a dim 📒 0 when empty. The active topic appears as 🧭 <topic>, or a dim 🧭 - when none is set. Readonly adds a warning-coloured 🔒 readonly indicator that disappears when readonly is off.

2. Pressure cues above the editor

At serious pressure the interface also intervenes above the editor. At a valid context usage of 70% or more a warning widget appears there. Its guidance is topic-aware: with an active topic it tells the agent to spawn for more same-topic work and to hand off for different-topic work; without one it says to hand off soon unless a topic can be assigned cleanly. The widget is advisory, and it is removed once usage falls below 70% or cannot be normalised.

3. Commands and interactive overlays

The operator drives the product with slash commands. /notebook <topic> sets a human-owned active topic, reports it by notification, and refreshes the indicators. Bare /notebook opens a selector headed with the current page count; it lists pages alphabetically and shows at most ten rows at once. An empty selector explains that pages are created with notebook_write and offers Escape to close; a nonempty one advertises up/down navigation, Enter to select, and Escape to close. Selecting a page shows its body truncated to 500 characters plus ... for display only — the cap applies to the overlay, not to the stored page or a later read — and any key then closes the overlay.

/handoff requests a deliberate context boundary; with no direction it reports Usage: /handoff <direction>. A requested handoff shows 🤝 Handoff requested — waiting for eligible context or 🤝 Handoff required — ready to compact according to eligibility, and a queued or running compaction is shown as 🤝 Handoff in progress. /readonly toggles the research posture, but only in an attached UI, notifying whether it is enabled or disabled; Ctrl+Shift+R does the same only while Pi is idle. Without an attached UI, bare /notebook and the readonly toggle are deliberate no-ops.

4. The Model Groups manager

Model Groups map semantic roles to replaceable provider/model pools. /model-groups opens its manager only in TUI mode; RPC mode is rejected with /model-groups requires TUI mode. The list shows boot-validation counts and marks any group with visible degraded, unavailable, override, or capability warnings. The operator can add a group, and the manager asks for confirmation before deleting a selected group. Adding a model walks through provider, then a searchable model list, then thinking level; the picker offers only authenticated models.

5. Watching a spawned child work

spawn delegates a focused task to a child agent in a separate context and returns only its condensed result, so the parent's transcript stays clean. The child is still visible while it works: the parent renders it live, collapsed by default, showing up to three lines of the child's prompt and noting when more are available by expanding. It identifies the model in use — the selected model, or the routed group and model — and its thinking level. A running child summarises its latest action in real time as thinking, assistant text, or tool activity, previews at most five lines of its last assistant output, and reports how many lines remain. Token and cost statistics appear when available.

Expanding renders the child's full message-component history, indented by four spaces. Once a child's first result renders, the parent owns its live view; disposing the parent session aborts and cleans up a still-running child. The view re-renders when terminal width, expanded state, or image-display setting changes, and otherwise reuses its cache.

Responsiveness is deliberate. The spawn renderer batches and draws bursty streaming updates at roughly 30 FPS, so high-frequency output does not stall the parent TUI; it keeps only the newest streaming state until the next frame and retries a failed render later. Malformed child events, missing tool definitions, and failed child-event subscriptions degrade the display rather than crashing the parent.

6. Inline tool output and diagnostics

Tool calls report themselves in the conversation. A notebook_write call shows the page name and its first-line preview, and once complete renders ✓ Saved "<name>" with that preview; expanding it also lists the current page names. A successful notebook_read renders ✓ "<name>" and reveals the full body only when expanded, while a missing page renders ✗ "<name>" not found. notebook_index renders 📒 N page(s), expands to the page list, and renders 📒 (empty) for no pages.

Diagnostics are not silent. Model Group configuration and boot-validation problems arrive as warning notifications, and a child result that exceeds 2,000 lines or 50 KB is capped with an advisory.

7. Limits, edge cases, and known gaps

Some behaviours are scoped to an attached UI or to a display layer. The high-usage widget disappears below 70% or when usage cannot be normalised. /notebook and the readonly toggle are no-ops without an attached UI, and /model-groups rejects RPC use. The 500-character cap applies to the overlay display, not the stored page or a read result. The spawn renderer keeps only the newest streaming state until the next frame and retries a failed render later; pi-schematic surfaces cleanup failures as a TUI error when a UI is available.

One behaviour sits outside the baseline rows and is recorded as a known gap rather than a contract: runtime-singletons.ts calls console.warn when replacing singletons while a write lock has pending operations. Because extension-host console.*/stderr output can corrupt Pi's ANSI rendering, this path can visibly corrupt the UI. It is exceptional (test harness / late re-registration), so production exposure is low.

Appendix — baseline behaviour rows

PB-TUI-01 … PB-TUI-45 — 45 atomic behaviour rows

Status bar and context pressure

ID Behaviour Evidence
PB-TUI-01 The status bar shows context usage as rounded ctx N% when Pi reports a valid percentage. tui.ts:40-46
PB-TUI-02 The context status shows ctx --% when context usage is unavailable or malformed. tui.ts:40-49
PB-TUI-03 Context pressure is colour-banded: green/dim below 30%, yellow/accent from 30% through 49%, orange/warning from 50% through 69%, and red/error at 70% or more. tui.ts:43-45
PB-TUI-04 A nonempty notebook appears in the status bar as 📒 N. tui.ts:51-54
PB-TUI-05 An empty notebook remains discoverable as dim 📒 0. tui.ts:51-55
PB-TUI-06 A set notebook topic appears as 🧭 <topic> in the status bar. tui.ts:64-68
PB-TUI-07 An unset notebook topic appears as dim 🧭 -. tui.ts:64-68
PB-TUI-08 Readonly mode adds a warning-coloured 🔒 readonly status indicator; it disappears when readonly is off. tui.ts:58-62
PB-TUI-09 At valid context usage of 70% or more, a warning widget is shown above the editor. tui.ts:72-81
PB-TUI-10 With an active topic, the high-usage widget tells the agent to spawn for same-topic work and handoff for different-topic work. tui.ts:75-78
PB-TUI-11 Without an active topic, the high-usage widget says to handoff soon unless a topic can be assigned cleanly. tui.ts:77-78

Commands, shortcuts, and interactive overlays

ID Behaviour Evidence
PB-TUI-12 /notebook <topic> sets a human-owned active topic, reports it by notification, and refreshes the indicators. index.ts:651-666
PB-TUI-13 Bare /notebook does nothing when no UI is attached. index.ts:668-670
PB-TUI-14 In the TUI, bare /notebook opens a selector headed with the current page count. index.ts:672-682
PB-TUI-15 The notebook selector lists pages alphabetically and displays at most ten rows at once. index.ts:682-702
PB-TUI-16 An empty notebook selector says to use notebook_write and offers Escape to close. index.ts:686-688, index.ts:723-726
PB-TUI-17 A nonempty notebook selector advertises up/down navigation, Enter selection, and Escape close. index.ts:723-726
PB-TUI-18 Selecting a notebook page shows its body in the overlay, truncated to 500 characters plus ... only for display. index.ts:706-716
PB-TUI-19 After a page body is displayed, any key closes the notebook overlay. index.ts:714-733
PB-TUI-20 /handoff with no direction shows Usage: /handoff <direction> as a TUI error. handoff/command.ts:25-30
PB-TUI-21 A requested handoff shows either 🤝 Handoff requested — waiting for eligible context or 🤝 Handoff required — ready to compact according to eligibility. handoff/copy.ts:3-6, handoff/command.ts:52-60
PB-TUI-22 A queued or running compaction uses the status text 🤝 Handoff in progress. handoff/copy.ts:8, handoff/tool.ts:342-343
PB-TUI-23 /readonly toggles readonly only in an attached UI and notifies the operator whether it is enabled or disabled. index.ts:493-512
PB-TUI-24 Ctrl+Shift+R toggles readonly only while Pi is idle. index.ts:521-526

Model Groups manager

ID Behaviour Evidence
PB-TUI-25 /model-groups opens its manager only in TUI mode; RPC mode receives /model-groups requires TUI mode. model-groups/command.ts:7-16
PB-TUI-26 The manager list displays boot-validation counts and marks groups with visible degraded, unavailable, override, or capability warnings. model-groups/tui.ts:678-703
PB-TUI-27 The manager lets the operator add a group and asks for confirmation before deleting a selected group. model-groups/tui.ts:699-701, model-groups/tui.ts:866-876
PB-TUI-28 The manager's add-model flow selects provider, searchable model, then thinking level, and its picker only offers authenticated models. model-groups/tui.ts:253-277, model-groups/tui.ts:837-863, model-groups/tui.ts:896-912

Spawn live rendering

ID Behaviour Evidence
PB-TUI-29 A collapsed spawn call shows up to three prompt lines and tells the operator when more lines are available by expansion. spawn/renderer.ts:53, spawn/renderer.ts:1290-1315
PB-TUI-30 A collapsed live child view identifies the selected model or routed group/model and its thinking level. spawn/renderer.ts:229-243, spawn/renderer.ts:984-992
PB-TUI-31 A running child view shows a real-time last-action summary for thinking, assistant text, or tool activity. spawn/renderer.ts:993-998, spawn/renderer.ts:1130-1141, spawn/renderer.ts:1212-1238
PB-TUI-32 A collapsed child view previews at most five lines of its last assistant output and reports remaining lines. spawn/renderer.ts:51, spawn/renderer.ts:1004-1017
PB-TUI-33 A child view includes token/cost statistics when those details are available. spawn/renderer.ts:302-316, spawn/renderer.ts:1019-1023
PB-TUI-34 An expanded child view renders its full message-component history indented by four spaces. spawn/renderer.ts:52, spawn/renderer.ts:1030-1051
PB-TUI-35 Once a child's first result renders, the parent owns its live view, and disposing the parent session aborts and cleans up a still-live child. spawn/renderer.ts:715-750, spawn/renderer.ts:1336-1343
PB-TUI-36 Child output re-renders when the terminal width, expanded state, or image-display setting changes; otherwise the cached rendering is reused. spawn/renderer.ts:951-967
PB-TUI-37 Bursty streaming updates from a child are batched and rendered on a roughly 30 FPS cadence, keeping the parent TUI responsive during high-frequency output. spawn/renderer.ts:62, spawn/renderer.ts:348-441, spawn/renderer.ts:1251-1271
PB-TUI-38 Malformed child events, missing tool definitions, and failed child-event subscriptions degrade the child display instead of crashing the parent TUI. spawn/renderer.ts:199-205, spawn/renderer.ts:660-669, spawn/renderer.ts:824-837, spawn/renderer.ts:1251-1271

Inline tool output, notifications, and safe diagnostics

ID Behaviour Evidence
PB-TUI-39 An inline notebook_write call shows the page name and its first-line preview. notebook/tools.ts:100-108
PB-TUI-40 A completed notebook_write renders ✓ Saved "<name>" with its preview; expanding it also lists current page names. notebook/tools.ts:111-122
PB-TUI-41 A successful notebook_read renders ✓ "<name>" and reveals the full body only when expanded. notebook/tools.ts:177-191
PB-TUI-42 A missing notebook_read renders ✗ "<name>" not found. notebook/tools.ts:177-184
PB-TUI-43 notebook_index renders 📒 N page(s), expands to the page list, and renders 📒 (empty) for no pages. notebook/tools.ts:247-257
PB-TUI-44 Model Group configuration and boot-validation problems are delivered as warning notifications rather than silently ignored. index.ts:944-955
PB-TUI-45 A child result is capped at 2,000 lines or 50 KB and reports an advisory when truncation occurs. spawn/index.ts:52-53, spawn/index.ts:108-132

Clone this wiki locally