guidesinteractive TUI
TUI defaults and scope
The reference TUI's consumer-facing product surface: subcommands, keybinds, status bar, layout, hooks, recording.
Full source summary
The reference TUI's consumer-facing product surface: subcommands, keybinds, status bar, layout, hooks, recording. The TUI is the wedge — the daily-driver adoption surface — and its differentiator is the wire: attach/detach, remoting, and a human and their agents sharing the same live terminals. It is held a pure consumer with no protocol privilege by ADR-0017. What's normative lives in ../spec/; this file is the human-facing reference for the tmux-shaped consumer that ships in tree.
11. Things we explicitly do not ship
Repeating from CONTRIBUTING.md because the design decisions here lean
on these:
- No embedded scripting language. No tmux-style
if-shell, no format-template DSL with conditionals. Templates are interpolation only. - No tmux-style copy-mode reimplementation. No second parser for selection boundaries, no mouse drag selection, and no custom clipboard format path. The client may expose a focused-pane copy-mode projection for cursor movement, viewport scrolling, highlighting, and literal search over mirrored scrollback, then delegate extraction/formatting to libghostty and native clipboard behavior.
- No multi-row status bar, no widgets, no themes-as-config. The status bar is one row. Themes are color slots, not a styling engine.
- No embedded plugin runtime in core. Plugin manifests are declarative config today. Future runtime surfaces execute argv commands over the same CLI/socket contract instead of embedding a scripting language.
- No homegrown crypto. Transport is the right layer; SSH and Unix socket perms cover it.
12. Defaults table
The shipped defaults, in one place:
| Setting | Default |
|---|---|
| Shell | defaults.shell; unset → $SHELL, fallback /bin/sh |
TERM advertised to panes | xterm-256color (phux-7vx/phux-0o8; set defaults.term = "ghostty" to opt in) |
| History limit per pane | 50 000 lines |
| Backpressure threshold | 32 unacked frames |
| Journal size cap (per pane) | 10 MiB ring |
| Prefix key | C-a |
| Which-key popup | on, 600 ms hesitation delay |
| Pane on PTY exit | close |
| Mouse | on (defaults.mouse; false = pass-through only, §7) |
| New-pane CWD inheritance | inherit-focused (tmux-shaped) |
| Spawn-on-attach | defaults.shell (unset = inherit) |
| Session name template | "default" (supports ${cwd-basename}) |
| Window-size policy | smallest (shared Terminal geometry, ADR-0027) |
| Status bar | [{ kind = "windows" }] / [{ kind = "help-hints" }] / ["session-name", { kind = "time", format = " %H:%M" }] |
| Status bar position | bottom ([status] position, or top) |
| Activity / silence thresholds | activity off; silence 2 min when enabled |
| Resize on attach | aggregate min bounding box per session |
| Cursor blink | follow inner program request |
14. Out of scope, but on the radar
These are not in v0.1 but the design accommodates them so they don’t require breaking changes:
- Resilient remote transport (zmosh-style UDP/SSP). Hooks into the
Transportabstraction in the wire spec (see../spec/proto.md§4). - Native GUI client (libghostty surface). Talks the same protocol
as the TUI client — the client’s
libghostty_vt::Terminalalready parsesPANE_OUTPUTbytes locally (ADR-0013); a GUI client swaps the TUI’sRenderState-to-VT renderer for aRenderState-to-GPU renderer and reuses everything else. - Multi-user shared sessions. Today’s protocol already supports multiple clients per session; ACL and identity will be a future authenticated transport addition.
- Tabbed layouts (nested tab containers). The wire spec (see
../spec/L3.md§3.2) reserves theTABBEDlayout node. - Image protocols (sixel, kitty graphics). Under ADR-0013 these
ride on the
PANE_OUTPUTbyte stream like any other VT sequence; per-client gating happens in the server’s capability rewriter (see../spec/proto.md§6.2). TheSixel/KittyGraphics/Iterm2capability bits already exist; the work is in the rewriter, not the wire format. - tmux control mode (CC) frontend. Optional adapter that would let
a CC-aware terminal (iTerm2 today; Ghostty when 1.4+ binds its
parser to the GUI) render phux Terminals as native splits of that
terminal. The native byte-stream protocol (ADR-0013) stays primary
and strictly more capable; CC is one possible alternative consumer,
not a roadmap commitment. Per
ADR-0017 the
reference TUI has no protocol-level privilege, so a CC adapter
picks its tier set (typically L1+L3) the same way the native TUI
does. The earlier
CC_FRONTENDcapability bit in the wire spec (see../spec/proto.md§6.2) is reclaimed under ADR-0017; no capability bit is needed.