10 · The Terminal UI Layer

146 UI components, 87 state-management units, 50 files of a customized framework. This layer accounts for a large slice of the codebase's bulk, yet it almost never comes up in architecture discussions. This chapter fills that gap.

10.1 Writing a Terminal UI in React

First, the thing itself: Ink is a framework that lets you write terminal UIs in React syntax.

The upside is that you reuse React's entire mental model: components, state-driven re-rendering, hooks. The cost is that you're dealing with a “canvas” that can only show monospaced characters, has no concept of pixels, and can be resized by the user at any moment.

Claude Code forked its own copy of Ink

The src/ink/ directory has 50 files — their customized version of Ink. The filenames show what they changed:

10.2 The Four Biggest Components

10.3 Why the Input Box Is 347 KB

An “input box” sounds like it should be simple. But this one has to handle:

10.4 The Virtualized Message List

A long session can have thousands of messages. If every re-render walked all of them and computed their layout, the UI would freeze into uselessness.

“Virtualization” means: render only the few messages visible in the current viewport, and for the rest, remember only how tall they are.

The related components:

• VirtualMessageList.tsx (145 KB) — the virtualized list itself
• Messages.tsx (144 KB) — the dispatch logic for rendering messages
• ScrollKeybindingHandler.tsx (146 KB) — scrolling and keyboard navigation

The hard part: in a terminal, “how tall a message is” isn't fixed. It depends on terminal width (resize the window and every message's height changes), whether the content wraps, whether it contains code blocks, whether it's collapsed. So heights have to be cached and recomputed in bulk when the width changes.

10.5 Six Rendering States for Tool Results

Recall from section 4.1 that the Tool interface has more than 10 rendering methods. They correspond to the different states of a tool call:

That renderToolUseMessage receives “partial input” is worth noting:

/**
 * Render the tool use message. Note that `input` is partial because we render
 * the message as soon as possible, possibly before tool parameters have fully
 * streamed in.
 */
renderToolUseMessage(input: Partial<z.infer<Input>>, options): React.ReactNode

To let the user see “what the agent has started doing” as early as possible, the UI starts rendering before the arguments have finished streaming. So every render function has to cope with “this field might not exist yet.”

10.6 Collapsing: Avoiding Screen Flood

/**
 * Returns information about whether this tool use is a search or read operation
 * that should be collapsed into a condensed display in the UI. Examples include
 * file searching (Grep, Glob), file reading (Read), and bash commands like find,
 * grep, wc, etc.
 *
 * - `isSearch: true` for search operations (grep, find, glob patterns)
 * - `isRead: true` for read operations (cat, head, tail, file read)
 * - `isList: true` for directory-listing operations (ls, tree, du)
 */
isSearchOrReadCommand?(input): { isSearch: boolean; isRead: boolean; isList?: boolean }

An agent exploring a codebase might read 20 files in a row. If every read displayed its full content, the user's screen would be flooded and the information that actually matters (the model's reasoning and conclusions) would be buried.

So these operations collapse into one line, something like “Read 20 files.” And the criterion is “the specific content of this call,” not “the tool type” — it's the same Bash tool, but running grep should collapse while running npm test must not (the user needs to see the test output).

10.7 87 State-Management Units

The hooks/ directory holds React custom hooks (something entirely different from the “user hooks” of chapter 9; they just share the English word). The names show how many kinds of state the UI has to manage:

10.8 The Interface Between UI and Kernel: Callbacks in ToolUseContext

The main loop from chapter 3 has no idea the UI exists. The interface between them is a set of optional callbacks in ToolUseContext:

setToolJSX?: SetToolJSXFn                    // lets a tool insert custom components into the UI
addNotification?: (notif: Notification) => void
appendSystemMessage?: (msg) => void          // append a UI-only system message
sendOSNotification?: (opts) => void          // OS-level notification (iTerm2/Kitty/bell)
setInProgressToolUseIDs: (f) => void         // which tools are running (draws the spinner)
setHasInterruptibleToolInProgress?: (v) => void
setResponseLength: (f) => void
setStreamMode?: (mode: SpinnerMode) => void  // the spinner's form
onCompactProgress?: (event: CompactProgressEvent) => void
setSDKStatus?: (status: SDKStatus) => void
openMessageSelector?: () => void
requestPrompt?: (sourceName, summary) => (request) => Promise<PromptResponse>

All of them are optional (marked with ?). That's the key — in headless mode none of these callbacks exist, and the kernel works as usual, just without producing any UI side effects.

One callback's comment explains the boundary of this design:

/** Append a UI-only system message to the REPL message list. Stripped at the
 *  normalizeMessagesForAPI boundary — the Exclude<> makes that type-enforced. */
appendSystemMessage?: (msg: Exclude<SystemMessage, SystemLocalCommandMessage>) => void

Put plainly: append a “UI-only” system message to the interactive UI's message list. It gets stripped at the “normalize into API format” boundary — and that Exclude type enforces this at the type level.

10.9 A Fun Detail: ANSI to PNG

utils/ansiToPng.ts, 209.9 KB — the largest file in the utils/ directory.

What it does: renders terminal output (text with ANSI color control codes) into a PNG image.

It serves the “share” feature — when a user wants to send a stretch of conversation to a colleague, plain text loses all the colors and formatting. Converting to an image preserves the terminal's visual look intact.

Why so big? Because it has to implement its own font renderer: parse the ANSI sequences → compute each character's position → draw glyphs onto a pixel canvas → handle the widths of Chinese characters and emoji → encode as PNG. All of that is free in a browser (the browser does it for you); in a command-line program, every bit has to be written by hand.