TUI runtime

The terminal user interface (TUI) renders session and runtime state through components. Components return terminal cells and semantic styles; the renderer computes a differential update instead of repainting unrelated rows.

How are input and rendering routed?

Terminal decoding turns bytes and escape sequences into key events. Focused overlays receive input before the prompt editor and global actions. State changes schedule a render, layout produces the next frame, and the diff layer emits only changed terminal regions.

How do I extend interactive surfaces?

Extensions can open a modal through ctx.ui.custom only when an interactive UI host exists. Custom tools may provide renderers for calls and results while preserving a plain-text representation for headless clients. A renderer must not become the only copy of durable tool output.

Read packages/tui/src for the component and rendering contracts, and packages/coding-agent/src/tui for the session-aware components built on them.

Use the TUI interaction style guide when adding a selector or manager. It defines the shared frame, responsive density, search and escape behavior, plain-text state semantics, and asynchronous feedback expected from interactive surfaces.

How are development native prerequisites kept current?

bun run dev, bun run test:ts, and the coding-agent package’s bun run test prepare the source-matched native addon automatically. The bootstrap checks a fingerprint of native sources, build inputs, and the host binary, then validates all runtime exports declared by the generated bindings in a fresh subprocess. Changed sources, missing artifacts, or incompatible bindings trigger a build; readiness is recorded only after the rebuilt addon passes another fresh-process check. An unchanged, verified checkout does not rebuild on every invocation.

For direct bun test <file> or direct source CLI invocation, first run bun scripts/ensure-dev-native.ts. Bare bun test does not run package lifecycle scripts. Do not patch a JavaScript stub to add PowerAssertion or another missing export: the source and native addon must match. A failed bootstrap reports the build or compatibility error and exits nonzero; follow the Rust/Zig prerequisites in DEVELOPING.md. Development checks require a host build, so unset cross-compilation targets before running them.

Validate visual changes in a real pseudo-terminal at narrow and wide widths, in light and dark themes, and with keyboard focus visible. A component must clip or wrap to the width it receives, restore terminal modes after failure, and expose the same durable result to headless clients. When an overlay closes, focus returns to the prior owner; when the terminal disconnects, cleanup must remain safe to run again.