02. UI
Model
The compositor owns the terminal and lays out panes. The protocol describes renderer-independent primitives. The default frontend implements the wire compositor; the experimental OpenTUI adapter below is migrating semantic views to native widgets while preserving host ownership.
Primitives
- Pane — a surface: a named cell buffer (
wl_surface). A plugin declares a surface; the compositor allocates a slot for it. - Site — a layout slot (
xdg_toplevel) that a pane binds to. Layouts are swappable, like tiling schemes in Sway. - Status bar — a layer above everything (
layer-shell): active model, token budgets, workflow state, plugin roster. - Focus / input routing — input is delivered to the focused pane; a click moves focus, as in a window manager.
- Damage tracking — a pane marks changed regions (
invalidate); the compositor redraws only those, not the whole screen.
Shipping terminal window controls
The normal CLI currently uses Ink. Its [Arrange] / Alt+w mode exposes the existing tiling tree directly: focus, directional moves, columns/rows, resizing, fullscreen and workspaces. The dock identifies the mode and focused window; ordinary typing resumes with i. Mode input cannot submit a draft or settle a model question or permission request. [Windows] / F2 / /windows opens a searchable inventory across workspaces and closed views, including the existing main conversation. Opening a plugin entry uses its actual declared UI route. Escape returns without changing the previous editor or its cursor.
See the terminal controls for the full key map, custom-editor bindings and form behavior. These shipping controls and the experimental OpenTUI preview below have separate entry points and key maps. The deterministic preview is separate from the experimental application frontend.
Experimental OpenTUI application frontend
Use compositor --renderer opentui for the actual configured application, or
bun packages/app/src/bin.ts --renderer opentui from a source checkout. Ink
remains the default. Renderer selection requires an interactive terminal; it
cannot be combined with --plain or a headless prompt. A source launch needs
Bun; native archives carry the renderer library, worker and parser assets.
This frontend uses the normal provider router, credential store, plugins and
session repository. /settings, /models, /providers, /plugins,
/marketplace and loaded UI-routed commands open their actual interfaces while
Main works or waits for an answer. Plain plugin text, action rows, tables, tabs,
search fields and raster contributions use native widgets. Plugin code stays
in the host. In Main, Enter queues a follow-up while the model runs and Tab
sends steering when supported; the window shows the accepted input. User
placement rules and saved window trees remain authoritative.
Portable ui.appearance contributions update native colors, window borders and
title controls, transcript labels/welcome, optional hints and current Main tool
details without replacing the editor or private request owners. Enable ui-theme
to use /theme slate|amber|mono. Omitted fields retain this frontend's defaults.
See appearance and publication semantics.
Composer attachments retain their producer's status when images are unavailable
or the pane is compact. With enough space, actual Kitty or SIXEL capabilities
select native images; SIXEL additionally needs current queried pixel geometry.
Reduced motion and disabled graphics keep the compact status. No block-art
replacement is generated. A hidden composer stops its subscription; a selected
custom editor owns the one visible attachment. /mascot pause|resume|off|status
and the other companion controls run immediately while Main works. See
companion playback.
Plugin raster views use negotiated Kitty or SIXEL image widgets; SIXEL requires known terminal pixel geometry. If capability or geometry is unavailable they retain the plugin's alt text. They also use Kitty Unicode placeholders through tmux when passthrough is enabled and capability negotiation succeeds. The placement is bounded to 20 columns by eight rows; unsupported terminals, disabled graphics, reduced-motion mode or an unconfirmed probe retain the plugin's alt text. Hidden views release their images. This tmux path is separate from native Kitty image widgets and does not establish support for screen or every terminal. When a focused plugin's own action adds a raster to its view, OpenTUI reveals it once. Scrolling or changing the selected action while that operation is pending keeps the user's newer position instead. Subsequent view updates preserve a manually scrolled position until the user navigates to another action. Up/Down or Tab also reveals the selected action after manual scrolling, including when it is the only available action.
Public ui.render and ui.invalidate hooks also apply to conversation, Tools,
Help, status and ordinary plugin views. Copies keep independent public viewport
and cache identities. A replacement retains the native editor, private request
and producer input owners. The normal footer has two public rows; Arrange and
Windows keep their own navigation footer. See view replacement.
/placement opens a private editor for a registered plugin window.
Choose its site, workspace, relative size, neighbor and focus
behavior. Apply moves the current window; Save rule and apply also writes the
normal project JSONC override. Cancel closes the editor without applying its
current fields; earlier applied changes remain. If saving finishes after you
select another window or workspace, the rule and placement still apply without
taking focus from that newer selection. Placement rules target plugin windows;
Main copies, Tools and Help can also serve as neighbors. The native editor
offers at most 198 plugin targets and 200 Neighbor choices, including Workspace
default and excluding the current target. Additional host copies consume the
neighbor capacity. If either list exceeds its limit, the editor explains the
limit and asks you to unload a plugin instead of dropping entries. A selected
placement controller can inspect the complete admitted anchor list. After Save,
the host checks that the target and neighbor are still the same current windows
before applying geometry.
Manual approvals, questions, questionnaires and forms initiated by an explicit UI operation occupy its private request window. Main keeps its own question, selected answer and draft. Different operations have separate inboxes, including operations from the same plugin; one operation serializes its own requests. An immediate command needs no declared UI component to receive such a window. Only the focused request accepts native input, and stale or foreign request IDs cannot settle it. Approvals display the exact action and offer Alt+Y Allow once or Alt+N Deny after the ordinary Core policy and automatic review pipeline. Answering or cancelling a current, focused request is fresh user intent for its ordinary operation, so saving a reopened or zoomed form can return to its result. This intent is captured before the continuation runs; a later window selection still takes precedence. Background request windows remain passive.
Closing a request window hides it. F2 reopens the same request with its selected answers, field cursor and validation state. Escape or Cancel cancels a question or form. Ctrl+C leaves navigation first; in a request window it denies the current approval or cancels the current question/form. In a work window it cancels that operation and its foreground tools. Ctrl+X in Main interrupts only Main. Private form values return directly to their requesting plugin, outside model messages and journals; UI-tool question results retain their separate operation audit and stay out of Main's transcript and replay. Finder searches safe window titles, never question text, answers or form values.
Explicit retained/background input has its own request owner, even if its launcher is still active. It opens without taking keyboard focus. Ending the launcher or interrupting Main does not cancel it; answering/cancelling the request, its requester signal, plugin unload or application close settles it. Truly unscoped requests still use Main's FIFO. Provider selection affects subsequent requests, including the continuation of an already-running turn.
Delegated agents and independent managed agents receive separate private request
windows for approvals, questions, questionnaires and forms. Titles identify the
request number, producing agent, direct parent and originating tool when available.
The via label names the original invocation; an approval's body shows the
effective action after any tool rewrite. Matching
agent names do not merge their requests. These windows use the producing Core's
selected controllers, open passively unless a still-current UI operation owns
the launch, and leave Main's pending answer and draft intact. F2 Windows reopens
a hidden request; answering one never answers another agent's request.
Replacing Main with /resume cancels its old delegated requests, including
detached descendants. An independent managed agent and its pending requests
remain live across that replacement; subsequent requests use the newly committed
UI channel. Closing or archiving that agent cancels its outstanding input.
Application exit cancels all remaining requests. Private forms return to the
requesting plugin without adding their values to model messages or journals.
Up to four UI operations and Main-plugin background request owners can remain active at once. A foreground operation reuses its own slot for its request FIFO. Further actions show a retry notice; search edits retain the latest queued value until capacity is available. A background request refused at capacity does not fall back into Main. Delegated and managed agents' private request windows do not consume these four UI operation slots. Main's model turn has a separate lifetime.
The top bar provides stable Alt+W Arrange, F2 Windows and Alt+0 Main controls. Window tabs scroll horizontally instead of adding rows as forms and plugins appear. Their order does not change the control keys. Alt+H/J/K/L or Alt+arrows changes spatial focus; Alt+Shift+direction moves a window, Alt+1…9 changes workspace, and Alt+Shift+1…9 moves it there. Alt+Tab cycles the workspace's windows; Alt+Shift+Tab reverses it. A terminal or desktop can reserve these chords before the application receives them. Zoomed windows show Zoomed in normal mode, with Alt+W, then F, to restore tiles. Escape leaves Arrange and resumes typing in the focused window.
Arrange displays WINDOW MODE, zoom state and the selected window. Use h/j/k/l or arrows to focus, Shift+direction to swap windows, b/v for columns/rows at the nearest split, +/− to resize, f to zoom, q to close, 1–9 to switch workspace, Shift+1–9 to move there, and Tab/Shift+Tab to cycle. The explicit split axis also sets the future split direction. w opens Windows, i returns to Main, and Escape leaves Arrange at the current window. Typing in this mode cannot enter a draft or answer a pending question/approval. Pasted text is ignored as window commands. Closing a view keeps its agent and resident editor alive.
In Arrange, n creates another Main window, t creates a Tools window and ? opens a new Help window. The same actions appear in F2 Windows as New Main window, New Tools window and New Help window. Alt+Enter keeps its answer/form submission behavior. These window actions do not submit a model prompt or start another agent.
Main copies share one conversation, draft, cursor, undo history and pending
question/approval/editor lease. Each window has its own transcript scroll
position. One resident input follows the focused Main copy; other copies show
the transcript and pending status. Selecting a plugin window parks that input
at its last Main window. Closing all Main windows keeps the input and agent
alive without opening a replacement automatically. F2, Alt+0 or /chat return
to an existing Main view; /chat never allocates another copy and accepts no
arguments. Use /btw for an independent side agent.
Saved Ink window-N session, Tools and Help views retain their IDs, open/closed
state, workspaces and split ratios when opened with this frontend. New windows
allocate after the highest saved number, including closed windows. Tools copies
share Main's bounded tool activity stream; Help shows the configured frontend's
controls. The layout stores window metadata, not drafts, answers or private form
values. The built-in OpenTUI Main editor saves its unsent text privately per
session, up to 64,000 UTF-16 code units. Resume that session to restore the last
acknowledged text; restoring never submits it. A process killed during a write
may lose the newest unacknowledged input. A normal Ctrl+C exit waits for pending
draft writes. While waiting, another Ctrl+C explicitly exits without waiting;
other keyboard input, a paste or a mouse click cancels the exit. If a write failed, the
application stays open so you can return to the draft and retry or explicitly
exit without saving. Cursor, undo and scroll remain in memory.
Saved drafts are plaintext under the project's private state directory in
main-drafts-v3; directories and files are created with restrictive permissions
where supported. Superseded versions and old experimental files can retain text;
cleanup is logical deletion, not secure erasure from backups or filesystem
snapshots. Do not put secrets in drafts unless this local storage is appropriate.
A draft that may already have been submitted is shown for review: Ctrl+R makes it
editable and a separate Enter sends it. For conflicting versions, use 1–9 or click a row to preview, Enter or the
Choose previewed draft action to choose, Ctrl+N/P to change page and Ctrl+R
to refresh. If an
in-memory draft differs from a saved one during a session switch, Ctrl+E toggles
the preview, Ctrl+L keeps the local text and Ctrl+R uses the saved text.
This persistence currently applies to the built-in OpenTUI editor, not Ink or selected plugin editors. Reload and interactive session resume keep resident input while replacing expired Core-bound capabilities.
Ctrl+arrows in Arrange retile the focused window at the corresponding edge of its directional neighbor: left/right insert beside it, up/down above/below it. This can create a nested split while keeping focus on the moved window. A successful move restores tiles from zoom; without a live neighbor it changes nothing. Other branches keep their proportions. Shift+direction still swaps the two windows. Ctrl+arrows outside Arrange retain native editor behavior; Ctrl+H/J/K/L are not window commands. Keyboard repeat does not repeat a retile.
Arrange also names the exact nearest keyboard split: columns or rows, its rounded
saved first/second proportions, and the side that + grows. A warm heavy line
marks that split's existing divider while it is visible. The saved ratio can
differ from the cell geometry because readable tiles have minimum dimensions.
If the target is hidden by zoom or available space, the status
explains why and draws no substitute divider. A lone or empty workspace shows
the next split direction and that there is no resize target. The cue stays out
of Finder and pointer gestures; mouse resizing retains its existing target.
The workspace bar leads the shell. An asterisk marks workspaces with open windows; the active workspace is highlighted. All nine workspace targets remain available, including in a 38-column terminal. The window strip shows only open windows on the current workspace, including windows temporarily hidden by readable projection or zoom. Closed windows and windows on another workspace remain in the finder. An empty workspace names F2 as the way to open or restore a window.
A plugin window's first publication is passive when its resolved placement has
no explicit focus preference: it can appear without changing the input owner or
switching workspace. Explicit plugin hints and configured focus: true/false
preferences remain available; use a saved focus: false rule for a producer
whose explicit focus requests should stay passive. Ordinary updates do not
reopen a closed window or reapply its first-publication focus.
An explicit command, action or current Finder choice can open its result, but a later window-navigation action takes precedence over delayed autofocus. This includes selecting Main again, changing workspace, selecting another pane, or opening Arrange/Windows. Delayed input from that operation remains available in its request window without taking focus from the newer selection. Background requests always stay passive. A retained producer can still satisfy the current Finder choice; an abandoned picker cannot create a late replacement window.
F2 / /windows opens a private searchable inventory of Main, current plugin views and forms, and loaded declared UI routes. It identifies workspaces and closed/available windows. Search uses titles and public command names, with a 512 UTF-16-unit limit; form values and descriptions are excluded. Native cursor, undo and paste editing remain available. Arrows select, Enter or a row click opens, and Escape restores the previous workspace/focus/fullscreen without rolling back concurrent publications. Selecting an unpublished route waits for its verified fresh view; cancellation or a new selection invalidates that opening. A detached view with no refresh route remains unavailable. Reopening Main uses its existing session and draft. Search is not sent to the model, journal or saved layout.
Outside navigation, native forms use Tab/Shift+Tab and explicit action buttons
or Alt+Enter. Main uses Alt+I to switch between its answer and draft.
Selected approval, question and form controllers use their own controls and
validated views instead. Main starts those requests in Draft mode; Alt+I or Answer gives
input to the controller while keeping the message draft and cursor parked.
An idle Main can send an ordinary message from Draft mode while its selected
local form remains open; selected questions and approvals retain their input gate.
Focused independent request windows give input directly to their controller.
Closing and reopening preserves its state. F2 Windows, Arrange, Main and the
window-navigation shortcuts remain host controls. See
private controllers for input precedence
and result validation. Custom approval scopes still pass through normal Core
policy; the native buttons continue to allow only one call.
Selected editors use their own validated view and bindings in Draft mode; the
native composer remains parked. An available focused selected Draft can own
F2, as in the documented F2-send example. Use Alt+W, then W, or the
Windows button to navigate from it. F2 Windows applies everywhere else,
including Answer mode and other windows. Accepted and Queued indicate actual
Core ownership; a rejected input restores the visible draft/cursor before the
next queued edit. A later model failure does not restore an accepted submission.
Commands and file discovery stay private and expire with the editor/Core.
--resume ID restores the actual saved session; /history uses its normal
repository. Unsent selected-editor drafts remain in memory, not across process exit.
During an interactive session switch, Main and the status bar show Restoring until startup
finishes. Input submitted during this transition is not sent; a selected editor
restores its draft so it can be submitted after Main returns to Ready.
If an interactive session switch opens its session but startup fails, new work
waits for an explicit /reload retry. Its input channels remain available for
recovery; failed startup does not permanently close the new session's inbox.
Completing an interactive session switch also respects newer window navigation
instead of forcing Main back into focus after startup.
The same plugin owner can republish a fresh source after resume without reopening
its closed window or resetting the user's workspace, tree or split ratios.
Selected history and placement controllers now open independent private windows. History browsing works while Main waits for a question, using its native query input and the controller's semantic selection/actions. Placement uses actual registered windows and anchors with normal project-rule saving. Arrange close hides the state; Ctrl+C closes the controller and cancels its pending input. Unavailable selections show a constant error with navigation still available. See private controller lifetimes.
This is an opt-in migration stage. The configured app now uses the negotiated
native protocol for presentation
and input, while the separate OpenTUI grid client accepts the compatible
source/send event log. Native widgets retain their local draft and undo state;
later input waits for host admission rather than model completion. Window and
workspace mouse selection also waits behind earlier queued keyboard input, so
text typed before the click stays with its original window. If a clicked window
body moves or is hidden before the selection is applied, OpenTUI selects or
reopens that same window if its owner still exists and the active workspace
has not changed.
Other pointer gestures against changed geometry are
discarded; repeat them on the current layout. A rejected
plugin-field edit is retried against the current revision only while the same
field, producer value and focused window remain current; a rejected edit that
cannot be recovered displays an error. A semantic input may explicitly bind Enter
to an advertised action; fields without this binding keep their existing behavior.
If the selected window's owner disappears before a queued click is admitted,
OpenTUI holds subsequent text instead of routing it to another window. Click an
ordinary input field or press Alt+0 to recover it in Main; private requests do
not accept this recovered text. This temporary recovery is kept in memory and
does not survive application exit. Escape discards it. Pending
actions and shortcuts, including Enter, are cancelled and must be invoked again.
Remaining
migration gates include wider physical terminal/media coverage and qualification
of the exact release candidate. Ctrl+C on an immediate-command window cancels that invocation
and its foreground internal tools or auxiliary model call, while Main and
neighboring command windows continue. Explicit background work keeps its
independent lifetime. Closing a window only hides it; use Ctrl+C to cancel its
operation. These gaps and the
migration gates prevent a
default-renderer switch or a stable 1.0 claim.
OpenTUI conversation prototype
Run npm run opentui:preview in a terminal from a source checkout with
Bun 1.4.4 and installed workspace dependencies. This opens a local preview
with two independent agent conversations, a workflows table and plugin management.
The demo starts a sample workflow and uses a deterministic local provider.
It stores state in a temporary directory for the life of the preview.
Main and Side start in two visible tiles. A pane's visibility and keyboard focus are independent. The focused title and border identify the input destination. Opening another pane splits the focused pane. All registered views remain available from the top bar, including panes closed or moved to another workspace. Narrow terminals keep every split that can give both children useful rectangles: at least 24 columns and 6 rows per child, including title and borders. A 60-column area can show two columns; a 38-column area can show two rows when tall enough. When a split cannot fit, its focused branch fills that split's area while other fitting branches stay visible. Cycling still reaches collapsed panes. Widening restores the saved tree and proportions; projection does not rewrite them. The host uses the same binary tiling manager as the Ink frontend. OpenTUI receives resolved rectangles and focus, and keeps native widgets mounted while their bounds or visibility change. The configured application uses this same readable projection, without a separate 70-column single-pane rule.
| Control | Action |
|---|---|
| F2 / F3 | Open or focus Main / Side, switching to its workspace when already open |
| F4 / F5 | Open or focus Workflows / Plugins |
| F6 | Cycle the current workspace's panes, including collapsed panes |
| F7 | Change the nearest split orientation, or the next split direction when alone |
| F8 | Swap the nearest split's children |
| F9 | Zoom the focused tile, or restore the split |
| F10 | Close the focused pane; its top-bar button reopens it |
| Alt+Left / Alt+Right | Resize the focused pane's nearest split |
| Alt+H / J / K / L | Focus a pane to the left / below / above / right |
| Alt+Shift+H / J / K / L | Swap the focused pane with a directional neighbor |
| Alt+1…9 | Switch workspace |
| Alt+Shift+1…9 | Move the focused pane to a workspace and follow it |
| Mouse | Focus by clicking, drag a title to an edge or center, or drag a separator |
Dropping a title on a pane's edge creates a split; dropping it in the center swaps the panes. Dropping on a workspace button moves it there. Escape cancels a drag or resize. Window gestures temporarily suspend editor and approval keys. Closing a pane hides its view. Its agent continues, and reopening restores the same editor, unsent draft and in-process transcript.
- In Main, submit
hold mainto keep a response streaming. Type a draft. - Press F3 or click the Side title. Enter a message and submit with Enter or its Send button. Ctrl+J adds a newline. Both conversations keep independent drafts while focus moves. Ctrl+Z undoes a composer edit and Ctrl+Y redoes it, including after closing and reopening that pane.
- Press F4 for Workflows. Use ↑/↓ to select a row and Enter or a click to expand its details. Use F9 when a detail view needs more room.
- In a ready conversation, submit
request write. Review the tool, reason, path and arguments in the approval card. PgUp/PgDn scroll the details. Alt+Y allows this one call and Alt+N denies it. The buttons also work with the mouse. The composer keeps your draft while you review. - Move focus while an approval is pending. Each waiting chat shows an Approval badge. Approval shortcuts act only in the focused conversation. Ctrl+C closes the preview and declines outstanding requests.
Submit request question, request custom or request questionnaire in either
chat to exercise actual ask_user / ask_questions calls. A pending question
shows a badge and keeps the message draft available. Alt+I or Edit answer
switches between the draft and the answer editor. Selecting an option does not
submit it. Use Alt+Enter or Submit to send the complete answer; Escape
or Cancel cancels only the active input while in Answer mode. Invalid or missing
answers remain pending. Questionnaires support Back/Next and preserve earlier
choices, multiple selections and custom text.
Each conversation has its own FIFO of approval, question and form requests. Closing a window preserves its pending request and input draft. Another chat or Plugins remains usable while the requesting agent waits. Ctrl+X or Stop interrupts the focused agent's foreground turn, including its question; it does not answer a permission request. Ctrl+C closes the entire preview.
The trusted /preview-form command opens private Preview settings with
text, URL, password, select and toggle fields. Alt+I / Edit form opens its
editor, Tab moves between fields, and arrows or Enter change choices. Submit
with the named action button, Alt+Enter, or Enter after tabbing to that action;
Escape cancels in the form editor. This demo command declares a five-minute
hook timeout; expiry cancels its pending form through the supplied signal.
The password field renders a mask. Its value returns directly to the plugin,
without becoming a chat message or catalog event. The demonstration saves only
its length and SHA-256 hash as a test receipt and makes no remote connection.
Immediate commands declared by loaded plugins can run during a model turn or pending question. Ordinary messages remain drafts until the agent is available. A private form alone also permits an ordinary message from Draft mode: the model can work while settings remain open. Foreground interruption preserves a form whose separate user-operation signal is still live. Question answers are model input, and never substitute for an execution permission decision.
The local approval example writes main-note.txt or side-note.txt inside
the temporary preview workspace. Each new write goes through the normal
tool permission policy.
Press F5 for Plugins. / focuses the filter. Enter leaves the filter, ↑/↓ selects a result, ←/→ selects an action and Enter runs it. Buttons support mouse input. Remove requires a second explicit confirmation, which Escape cancels. R or Refresh rereads the registered catalogs.
The preview registers an isolated local preview-market containing
preview-notes. Installation uses the real project extension store and leaves
the plugin inactive. Enable saves the selection. If Main is busy, activation
waits for it to become idle. The row distinguishes catalog, installed and loaded
versions, saved on/off selection and pending work. Update and removal retain
running package files until it is safe to apply them. Closing the preview
cancels its unapplied queued file operations. /preview-note in idle Main runs
the loaded plugin directly, records its version in plugin storage and posts a
notice, without asking the model.
The private renderer-opentui workspace owns rendering and native widgets.
The preview host translates core conversation events and plugin table updates
into its inputs. Selecting a workflow row returns that row's declared action
through the plugin's ordinary ui.press handler. The plugin owns expansion.
On a wide screen with negotiated Kitty graphics, the composer displays
the original idle or thinking Ghost. Set AGENT_GRAPHICS=off to hide it.
The host saves the full tree, ratios, open/closed panes, workspace and focus through the application's layout store. The browser bench keeps an isolated home across its Restart session action and verifies this restoration on disk and on screen, including an empty workspace. The standalone preview still uses temporary state for its lifetime. Layout restoration does not restore preview transcripts or unsent drafts after the process exits.
The shipped terminal still uses Ink. This preview covers nested windows, native composers, one-call permission decisions, workflow expansion and the local plugin lifecycle plus native questions and private forms. Selected private controllers are exercised by the configured application bench rather than this standalone demo. The configured application frontend owns production protocol, settings, placement, recovery and archive checks; success in this prototype alone cannot close those migration gates. Migration plan
Reference renderer implementation: Ink
React + Yoga flexbox: pane = Box, site = column/row, status bar = Spacer at the bottom. Scroll areas come out of the box in the new major Ink release: overflow="hidden" + contentOffsetY + the useBoxMetrics hook.
Starter layout:
┌──────────────────┬───────────────────────┐
│ │ panes: agents │
│ pane: session │ tasks │
│ (chat + stream) │ workflow │
│ ├───────────────────────┤
│ │ pane: inspector │
├──────────────────┴───────────────────────┤
│ status bar: model · tokens · plugins │
└──────────────────────────────────────────┘
Mouse: the reference renderer parses SGR mouse sequences and forwards input through the protocol. The compositor owns hit testing, focus, capture and drag/resize. See the terminal manual for bindings and the visual bench for actual PTY verification.
The Ink renderer selects interactive repainting from its output stream's
isTTY flag. A real terminal continues to receive live frames with inherited
CI or CONTINUOUS_INTEGRATION flags; those flags do not turn the running
interface into an exit-only frame. A redirected renderer output stream retains
static final-frame output.
The Claude Code lesson
Claude Code started on stock Ink and rewrote the render engine: the stock version allocates one object per terminal cell per frame (~24,000 objects at 200×120 every 16 ms) and diffs whole strings. Their fork: typed arrays instead of objects, double buffering, cell-level dirty tracking.
Conclusion: Ink's component model (React + Yoga) is permanent; the engine beneath it is a consumable that can be replaced without rewriting components. Hence the hard rule: the compositor consumes the core only through the versioned protocol, even when living in the same process with it. The seam matters more than the framework.
Swappable renderers
One protocol — any number of implementations:
- headless — JSONL over stdio or a unix socket: tests, scripts, external tools;
- TUI — Ink (the reference);
- web — a future implementation could transport the same protocol over WebSocket; a web renderer is not currently shipped.
External tools (fzf, tmux, a custom dashboard) become clients of the compositor — the "netlink move" that no existing CLI agent has.