Claude Code REPL: 5000 Lines Binding Every Subsystem

Every subsystem described in this series — the query loop, AppState, tools, permissions, MCP, memory, tasks, the Ink renderer — has one place where it actually gets assembled into a running product.

That place is REPL.tsx. At 5005 lines, it is the largest file in the codebase and the one that most directly answers the question: what does it mean for all these layers to work together?

File structure

src/
├── screens/
│   └── REPL.tsx

The REPL.tsx file has no meaningful subdirectory structure — it is intentionally monolithic. All coordination logic lives in one place so the binding between subsystems is visible rather than scattered.

Why REPL.tsx is different from a UI component

The first thing to notice about REPL.tsx is how few JSX nodes it returns relative to its line count.

Most of the file is state initialization, hook binding, and callback wiring. The actual render tree is compact. The complexity is in the coordination logic that connects 30+ subsystems so they all observe the same session state and respond to the same events.

This is the right design. The alternative — embedding coordination logic in JSX or spreading it across hooks — would make the binding between subsystems invisible. In REPL.tsx, all of it is in one place.

The 30+ hooks

The QueryGuard

The most important single design choice in REPL.tsx is the QueryGuard.

The problem it solves: without it, isLoading and isQueryRunning are two separate state flags that can get out of sync. The window between setting one and the other creates a race condition where a second submit can enter the query path before the first one has fully started.

The QueryGuard replaces both flags with a sync state machine that has atomic reserve and start semantics:

1. queryGuard.reserve() fires before the first await in executeUserInput — it claims the execution slot synchronously
2. queryGuard.tryStart() locks the state atomically
3. The state is exposed via useSyncExternalStore so all subscribers see it simultaneously

This means there is never a window where "someone thinks the query is not running, but a query has actually started."

The stale-read problem and the solution

REPL.tsx has many callbacks (onQuery, onQueryImpl, handlePromptSubmit) that fire much later than when they were created. If they read AppState through React closure captures, they will read stale values.

The solution is consistent throughout:

• For AppState fields that change frequently: read via store.getState() inside the callback, not via captured state
• For AppState fields that are stable across a session: captured closure is acceptable

The getToolUseContext function (which computes the full tool surface for a query) reads fresh MCP clients, permissions, and agent definitions from the store every time it is called. It never uses closure-captured values for these.

This is a subtle but important discipline. Violating it produces bugs where the agent uses tools from a previous MCP configuration, or applies permissions from before the user changed the mode.

The overlay priority stack

When multiple overlays want to show at the same time, REPL.tsx arbitrates via getFocusedInputDialog() — a priority-ordered function that returns the highest-priority overlay that currently has something to show:

1. Exit states suppress everything
2. Message selector (Ctrl+O fullscreen) takes priority
3. Active typing suppresses prompts for 1500ms (PROMPT_SUPPRESSION_MS)
4. Sandbox permission requests (pre-interrupt, highest-trust)
5. Tool permission dialogs (gated by animation state)
6. Prompt dialogs, elicitation, cost dialog
7. Onboarding flows (IDE setup, model switch, effort callout)
8. LSP recommendation, plugin hints, desktop upsell

This ordering is a product decision encoded in code. If a tool permission dialog and a cost dialog want to show at the same time, the tool permission dialog wins.

The messagesRef pattern (ref-as-source-of-truth)

One of the most specific design choices in REPL.tsx is how setMessages is implemented.

The standard React pattern is: call setState, then the next render sees the new value. But for paths like handleSpeculationAccept → onQuery — where a callback reads the message list immediately after calling setMessages — that next-render timing is too late.

Claude Code solves this with a ref-as-source-of-truth pattern:

// setMessages eagerly updates the ref BEFORE committing to React state
const setMessages = useCallback((update) => {
  const next = typeof update === 'function' ? update(messagesRef.current) : update
  messagesRef.current = next   // immediate — synchronous reads see new value
  rawSetMessages(next)         // schedules the React re-render
}, [])

Any callback that reads messagesRef.current after calling setMessages sees the updated value immediately, before React batching fires. This is the same pattern as Zustand's store — the ref is the canonical state, React state is the render projection.

The consequence: code that needs to read messages synchronously after mutation uses messagesRef.current, not the hook value. Code that only needs to display messages uses the hook value. These are two different reads of the same data.

The onSubmitRef stability optimization

REPL.tsx wraps onSubmit in a stable ref (onSubmitRef). Every MessageRow that renders during the session pins this callback at mount time.

The reason is memory. A 1000-turn session creates 1000+ MessageRow fibers, each with a closure over the REPL component scope. If onSubmit is prop-drilled as a normal function, every turn that closes over REPL's scope keeps the entire previous scope alive. At ~35KB per REPL scope, that accumulates.

The stable ref breaks the closure chain: MessageRow fibers hold a reference to the ref object (which never changes) rather than to the specific function in the scope at mount time. Old REPL scopes can be garbage-collected once React finishes with them.

This is a memory optimization that only becomes visible in very long sessions — but the 35MB number is large enough to notice in production.

Feature-gate dead code elimination

Several hooks in REPL.tsx are conditionally imported based on feature flags:

const { useProactive } = require('./features/proactive')   // PROACTIVE/KAIROS
const { useVoice } = require('./features/voice')           // VOICE_MODE
const { useCoordinator } = require('./features/coordinator') // COORDINATOR_MODE

These use feature() from bun:bundle — a compile-time constant that Bun evaluates during the build. When a feature flag is disabled, the if (false) branch is eliminated entirely. The module is never loaded; the hook never runs.

This matters for external builds (VS Code extension, JetBrains) where ant-only features must not ship. Dead code elimination via compile-time constants is more reliable than runtime checks because there is no way for the code to accidentally execute.

Deferred rendering as a latency optimization

useDeferredValue(messages) on the message list is one of the quieter performance choices in the file.

React's deferred rendering means the reconciler yields every ~5ms to check for higher-priority updates (like user input). This keeps the input box responsive during expensive message tree re-renders after a long streaming response.

Without it, typing during message rendering produces noticeable lag because the reconciler works through the full tree before processing the keypress.

The deferredBehind counter tracks how many messages are pending deferred rendering. The UI can use this to show a loading indicator during the catch-up phase.

Streaming architecture

Three streaming surfaces exist simultaneously:

1. visibleStreamingText — line-by-line preview of the model's in-progress text response. Cuts at the last newline so the partially-complete current line is not shown. Disabled if reducedMotion is set or if a cursor-up viewport bug is present.

2. streamingToolUses — tool call objects from the model during generation. Rendered by the Messages component, not by REPL directly.

3. streamingThinking — thinking block content. Auto-hides 30 seconds after streaming ends so it does not permanently clutter the conversation.

The ephemeral progress messages (bash tick updates, sleep progress) use a replace-not-append pattern. Without this, a 5-minute bash command would produce thousands of tick messages and make the message list unusable.

// QueryGuard: atomic reserve + start, exposed via external store
class QueryGuard {
private state: 'idle' | 'reserved' | 'running' = 'idle'
private listeners = new Set<() => void>()

// Step 1: reserve BEFORE any await — synchronous
reserve(): boolean {
  if (this.state !== 'idle') return false
  this.state = 'reserved'
  this.notify()
  return true
}

// Step 2: start ATOMICALLY — if state changed since reserve(), abort
tryStart(): boolean {
  if (this.state !== 'reserved') return false
  this.state = 'running'
  this.notify()
  return true
}

end(): void {
  this.state = 'idle'
  this.notify()
}

// Expose via useSyncExternalStore — all subscribers see change atomically
subscribe = (cb: () => void) => {
  this.listeners.add(cb)
  return () => this.listeners.delete(cb)
}
getSnapshot = () => this.state

private notify() { this.listeners.forEach(l => l()) }
}

// Usage in REPL
const queryGuard = useMemo(() => new QueryGuard(), [])
const queryState = useSyncExternalStore(queryGuard.subscribe, queryGuard.getSnapshot)

// Stale-read discipline: fresh store reads inside callbacks
const store = useAppStateStore()  // direct store reference

const onQueryImpl = useCallback(async (input: string) => {
// CORRECT: read fresh state at call time, not at hook creation time
const { mcp, toolPermissionContext } = store.getState()
const tools = computeTools(mcp.tools, toolPermissionContext)
// ...
}, [store])  // store reference is stable — no stale capture risk

// WRONG pattern (avoid):
// const { mcp } = useAppState(s => s)  // captured at render, stale in callback
// const onQueryImpl = useCallback(() => { use mcp here }, [mcp])  // re-creates on every mcp change