Repository navigation
Product Book TUI
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.
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.
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.
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.
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.
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.
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.
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.
PB-TUI-01 … PB-TUI-45 — 45 atomic behaviour rows
| 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 |
| 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 |
| 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
|
| 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
|
| 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
|