Claude Code UI Runtime: External Store, Custom Ink Pipeline, Session Control Plane

If you only look at the model loop, Claude Code looks like an agent client.

Reading src/state/AppStateStore.ts and src/ink/ink.tsx makes it clear it is also a terminal application runtime — one that must handle streaming messages, permission prompts, background tasks, MCP connection status, remote session indicators, and fullscreen selection simultaneously.

The UI layer is not presentation glue. It is part of the system design.

File structure

src/
├── ink/
│   └── ink.tsx
├── state/
│   ├── AppStateStore.ts
│   └── Store.ts

The core idea

The Claude Code UI runtime has two halves:

1. a session store that holds interactive runtime state
2. a terminal renderer that turns a React tree into a stable fullscreen TUI

Those halves meet in the REPL.

Why the state layer matters

AppStateStore.ts is the clearest sign that Claude Code is not built like a simple chat screen.

The state tree includes:

• permission mode and permission context
• task registry
• MCP clients, tools, commands, and resources
• plugin state
• agent definitions
• notifications and elicitation queues
• bridge and remote session status
• prompt suggestion and speculation state
• overlay and footer selection state

That is not "local component state."

It is session infrastructure.

Why the store is external instead of pure React state

The store implementation in state/store.ts is tiny on purpose.

Then AppState.tsx uses useSyncExternalStore selectors to expose state slices.

That architecture gives Claude Code three things at once:

• one canonical mutable session state
• predictable subscription semantics
• fewer unnecessary tree-wide re-renders

That matters because the app has many fast-changing subsystems in parallel.

onChangeAppState.ts is where state becomes side effects

A subtle but important file in this area is onChangeAppState.ts.

It centralizes "what else must happen when the state changes."

That includes:

• syncing permission mode outward
• persisting model changes
• persisting UI preferences like expanded view
• clearing caches when settings change
• re-applying managed environment variables

This is a strong design choice.

It means the mutation boundary and the side-effect boundary stay connected.

Why the Ink runtime matters so much

The terminal renderer is much more than "use Ink."

Claude Code has a real frame pipeline:

• reconcile React into Ink DOM nodes
• compute Yoga layout
• render into a screen buffer
• diff against the previous frame
• optimize terminal patches
• write to the terminal

That lets the product support:

• low-flicker updates
• fullscreen views
• selection overlays
• search highlight
• better resize recovery
• cursor management for IME and accessibility

ink.tsx is the UI equivalent of query.ts

query.ts owns the agent turn lifecycle.

ink.tsx owns the frame lifecycle.

That is the most useful analogy here.

It is where Claude Code keeps:

• frame buffers
• render scheduling
• alt-screen state
• cursor position strategy
• selection and search overlay state
• terminal cleanup guarantees

That is why this file deserves to be read as core runtime code, not as UI plumbing.

The real lesson

Claude Code's UI is not just "React components in a terminal."

It is a store-hosted, terminal-native runtime with:

• a session control plane
• a custom rendering engine
• explicit terminal behavior management

That is one of the main reasons the product feels like a real local runtime instead of a wrapper around model streaming.

// state/store.ts — tiny external store, no React dependency
class ExternalStore<T> {
private state: T
private listeners = new Set<() => void>()

constructor(initial: T) { this.state = initial }

getSnapshot(): T { return this.state }

setState(update: (prev: T) => T): void {
  this.state = update(this.state)
  this.listeners.forEach(l => l())
}

subscribe(listener: () => void): () => void {
  this.listeners.add(listener)
  return () => this.listeners.delete(listener)
}
}

// AppState.tsx — React integration via useSyncExternalStore
const appStateStore = new ExternalStore<AppState>(getDefaultAppState())

// Selector-based subscription: only re-renders when selected slice changes
function useAppState<T>(selector: (state: AppState) => T): T {
return useSyncExternalStore(
  appStateStore.subscribe,
  () => selector(appStateStore.getSnapshot()),
)
}

// Mutation — always goes through setState to trigger subscriptions
function setAppState(update: (prev: AppState) => AppState): void {
appStateStore.setState(update)
}