Claude Code v2.1.88 React Component Architecture Deep-Dive

Analysis Date: April 2, 2026 Codebase: /sessions/cool-friendly-einstein/mnt/claude-code/src/components Scope: 389 component files, 81,546 LOC Focus: Engineering architecture, composition patterns, state management, data flow

Executive Summary

Claude Code v2.1.88 implements a sophisticated terminal-based IDE using React in Ink.js rendering to the terminal. The architecture prioritizes:

State as the single source of truth via Zustand-like store with useSyncExternalStore
Selective re-rendering through fine-grained subscription selectors
Performance optimization via memoization, virtual scrolling, and React Compiler annotations
Modular permission system with 51+ permission-specific components
Real-time interactivity through terminal event handlers and keybinding contexts
Multi-agent support with teammate/swarm coordination via mailbox pattern

The architecture is deeply optimized for 2800+ message sessions without CPU pegging, featuring blit-based terminal rendering, conditional dead-code elimination via feature() gates, and lazy component loading for expensive features like voice mode and agent swarms.

Section 1: Component Hierarchy & Topology

1.1 Root Component Composition

The app layers multiple context providers in this order:

App (top-level provider wrapper)
├── FpsMetricsProvider (performance tracking)
├── StatsProvider (analytics store)
└── AppStateProvider (global state store)
    ├── MailboxProvider (teammate inter-process communication)
    ├── VoiceProvider (feature-gated: VOICE_MODE only)
    └── [Application Children]
        └── REPL (main screen container)
            ├── PromptInput (primary user interaction hub)
            ├── Messages / VirtualMessageList (message rendering)
            ├── StatusLine (status footer)
            └── [Overlay Dialogs via context]

App.tsx (56 lines, React Compiler optimized):

Wraps initialState and callback handlers
Uses _c annotations for React Compiler memoization
Provider nesting is immutable (enforced by HasAppStateContext guard)
Stats store is optional (headless SDK mode)

1.2 Main Screen Structure (REPL)

The REPL is the master orchestrator:

REPL (main.tsx logic, fullscreen layout)
├── FullscreenLayout (if isFullscreenEnvEnabled)
│   ├── Messages
│   │   ├── LogoHeader (memoized, prevents cascade dirty flag)
│   │   ├── StatusNotices (agent definitions, tool errors)
│   │   ├── VirtualMessageList
│   │   │   └── MessageRow[] (virtualized, memoized per-message)
│   │   │       ├── MessageRow dispatch logic
│   │   │       ├── Type-specific renderers
│   │   │       │   ├── UserMessage
│   │   │       │   ├── AssistantMessage / Thinking
│   │   │       │   ├── SystemMessage
│   │   │       │   ├── ToolUse / ToolResult
│   │   │       │   └── Attachments
│   │   │       └── Message Actions overlay
│   │   └── SearchHighlighting (textHighlight[] overlay)
│   ├── ScrollKeybindingHandler (scroll + acceleration curves)
│   └── PromptInput
│       ├── TextInput / VimTextInput (text editing)
│       ├── PromptInputFooter (pills + suggestions)
│       │   ├── BackgroundTasksDialog (tasks pill)
│       │   ├── TeamsDialog (teams pill)
│       │   ├── BridgeDialog (bridge pill)
│       │   ├── CompanionSprite (buddy pill)
│       │   └── Notifications (transient toasts)
│       ├── PromptInputFooterSuggestions (typeahead UI)
│       ├── PromptInputModeIndicator (display mode)
│       ├── PromptInputQueuedCommands (queued items)
│       └── PromptInputStashNotice (stash hint)
├── Modal Overlays (via OverlayContext)
│   ├── ModelPicker
│   ├── QuickOpenDialog
│   ├── GlobalSearchDialog
│   ├── HistorySearchDialog
│   ├── FastModePicker
│   ├── ThinkingToggle
│   ├── AutoModeOptInDialog
│   ├── Settings/Config (1,821 lines tabbed interface)
│   ├── LogSelector (1,574 lines session picker)
│   ├── TeamsDialog (714 lines team management)
│   ├── BackgroundTasksDialog (651 lines)
│   ├── InvalidConfigDialog
│   ├── ClaudeMdExternalIncludesDialog
│   ├── ChannelDowngradeDialog
│   ├── MCPServerMultiselectDialog
│   └── [51+ Permission dialogs]
└── Design System Components
    ├── Dialog (modal wrapper)
    ├── Tabs (tabbed navigation)
    ├── Pane (content area)
    ├── SearchBox (search input)
    ├── CustomSelect (dropdown)
    ├── KeyboardShortcutHint (help text)
    └── Divider (visual separator)

1.3 Component Classification

Screens (fullscreen, handle their own layout):

REPL: main interactive session screen
FullscreenLayout: optional viewport wrapper
Settings/Config: settings tabbed interface

Containers (coordinate child components):

PromptInput: text input orchestrator
Messages: message list master
VirtualMessageList: virtualization coordinator

Dialogs (modal overlays):

51+ permission components in permissions/
ModelPicker, QuickOpenDialog, HistorySearchDialog
BackgroundTasksDialog, TeamsDialog, BridgeDialog

Renderers (pure message display):

MessageRow: single message layout
StreamingMarkdown: markdown with syntax highlighting
AssistantThinkingMessage: thinking block display
ToolUse renderers (different per tool type)

Primitives (design system, reusable):

Dialog, Tabs, Pane, SearchBox, CustomSelect
KeyboardShortcutHint, Divider, Byline
Text, Box (from Ink.js)

Section 2: State Management Architecture

2.1 AppState Store Design

The application uses a Zustand-like store pattern with useSyncExternalStore (React 18 API). This is NOT Redux—it's a custom implementation optimized for terminal rendering.

AppStateStore.ts structure:

type AppState = {
  // Navigation & Views
  expandedView: 'teammates' | 'spinner' | 'compact' | null
  viewSelectionMode: 'agents' | 'messages'
  viewingAgentTaskId: string | undefined
  footerSelection: FooterItem | null  // 'tasks' | 'teams' | 'bridge' | 'companion' | 'tmux' | 'bagel'
  coordinatorTaskIndex: number

  // Input State
  input: string
  mode: PromptInputMode
  vimMode: VimMode

  // Model & Runtime
  mainLoopModel: string | null
  mainLoopModelForSession: string | null
  thinkingEnabled: boolean
  fastMode: boolean
  effortValue: EffortLevel

  // Permissions & Safety
  toolPermissionContext: ToolPermissionContext

  // Session Data
  messages: Message[]
  tasks: Record<string, Task>

  // Speculation (prompt suggestions)
  speculation: SpeculationState
  speculationSessionTimeSavedMs: number
  promptSuggestion: { text: string; promptId: string } | null

  // MCP & Services
  mcp: { clients: MCPServerConnection[] }

  // Team & Swarm
  teamContext: TeamContext | undefined

  // Feature State
  ultraplanSessionUrl: string | undefined
  ultraplanLaunching: boolean

  // Bridge & REPL
  replBridgeConnected: boolean
  replBridgeExplicit: boolean
  replBridgeReconnecting: boolean
  tungstenActiveSession: string | undefined
}

2.2 Store Implementation

File: src/state/store.ts

export function createStore(
  initialState: AppState,
  onChangeAppState?: (args: { newState: AppState; oldState: AppState }) => void
): AppStateStore {
  let state = initialState;
  const listeners = new Set<() => void>();

  return {
    getState: () => state,
    setState: (updater: (prev: AppState) => AppState) => {
      const newState = updater(state);
      if (newState !== state) {
        const oldState = state;
        state = newState;
        onChangeAppState?.({ newState, oldState });
        // Notify all subscribers
        listeners.forEach(listener => listener());
      }
    },
    subscribe: (listener: () => void) => {
      listeners.add(listener);
      return () => listeners.delete(listener);
    }
  };
}

Key Properties:

Single object reference for state (immutable updates)
Subscriber pattern with cleanup function
Optional onChange hook for side effects (analytics, persistence)
No batching (synchronous updates)

2.3 Subscription Patterns

Fine-grained selectors prevent unnecessary re-renders:

// Single field subscription (most common)
const verbose = useAppState(s => s.verbose);  // Only re-renders on verbose change

// Multiple independent subscriptions (not a single selector returning object)
const verbose = useAppState(s => s.verbose);
const model = useAppState(s => s.mainLoopModel);

// WRONG: Creates new object every render
const badSelect = useAppState(s => ({ verbose: s.verbose, model: s.mainLoopModel }));

// RIGHT: Select existing sub-object reference
const promptSuggestion = useAppState(s => s.promptSuggestion);  // { text, promptId } ref

store.subscribe() is used in non-React code:

// In query.ts, services, utilities
const store = useAppStateStore();
const unsubscribe = store.subscribe(() => {
  const state = store.getState();
  // React on state changes outside React render cycle
});

2.4 AppStateProvider Nesting Guards

AppState.tsx enforces single provider:

const HasAppStateContext = React.createContext<boolean>(false);

export function AppStateProvider({ children, initialState, onChangeAppState }: Props) {
  const hasAppStateContext = useContext(HasAppStateContext);
  if (hasAppStateContext) {
    throw new Error("AppStateProvider can not be nested within another AppStateProvider");
  }

  // ... provider setup
  return (
    <HasAppStateContext.Provider value={true}>
      <AppStoreContext.Provider value={store}>
        {/* Providers: MailboxProvider, VoiceProvider */}
        {children}
      </AppStoreContext.Provider>
    </HasAppStateContext.Provider>
  );
}

Why: Prevents accidental double-wrapping. Store is created once at mount via useState(() => createStore(...)).

2.5 Settings & Configuration Layers

Three-layer settings architecture:

1. GlobalConfig (disk: ~/.config/claude-code/config.json)
   ├── autoCompactEnabled
   ├── verbose
   ├── apiKey (normalized)
   ├── theme
   └── outputStyle

2. LocalSettings (project: .claude-code/settings.json)
   ├── spinnerTipsEnabled
   ├── expandedView
   ├── language
   └── replBridgeEnabled

3. UserSettings (user: ~/.claude-code/settings.json)
   ├── defaultView ('chat' | 'transcript')
   └── briefOnlyMode

4. AppState Runtime (in-memory)
   ├── mainLoopModel (mutable, session override)
   ├── thinkingEnabled
   ├── fastMode
   └── toolPermissionContext

Hierarchy: AppState defaults read from LocalSettings + GlobalConfig, but AppState mutations don't write back unless explicitly persisted.

2.6 Context Providers (Beyond AppState)

Provider	Purpose	Feature Gate
`FpsMetricsProvider`	Frame timing metrics	None (always)
`StatsProvider`	Analytics event buffering	None
`AppStateProvider`	Global state store	None
`MailboxProvider`	Team/agent message passing	AGENT_SWARMS
`VoiceProvider`	Voice input handling	VOICE_MODE
`NotificationsProvider` (PromptInput)	Toast notifications	None
`OverlayContext`	Modal/dialog active state	None
`PromptOverlayContext`	Prompt-specific overlays	None
`ModalContext`	Inside-modal detection	None
`KeybindingContext`	Keyboard shortcut registry	None
`ThemeContext` (Ink.js)	Terminal color theme	None

Section 3: PromptInput Deep-Dive (2,338 Lines)

The PromptInput component is THE user interaction hub. It's where text entry, command dispatch, agent communication, and input mode management converge.

3.1 PromptInput Props Interface

type Props = {
  debug: boolean;
  ideSelection: IDESelection | undefined;
  toolPermissionContext: ToolPermissionContext;
  setToolPermissionContext: (ctx: ToolPermissionContext) => void;
  apiKeyStatus: VerificationStatus;
  commands: Command[];
  agents: AgentDefinition[];
  isLoading: boolean;
  verbose: boolean;
  messages: Message[];
  onAutoUpdaterResult: (result: AutoUpdaterResult) => void;
  autoUpdaterResult: AutoUpdaterResult | null;

  // Input management
  input: string;
  onInputChange: (value: string) => void;
  mode: PromptInputMode;
  onModeChange: (mode: PromptInputMode) => void;

  // Stash (pause/resume input)
  stashedPrompt: { text: string; cursorOffset: number; pastedContents: Record<number, PastedContent> } | undefined;
  setStashedPrompt: (value: ...) => void;

  // Submission
  submitCount: number;
  onSubmit: (input: string, helpers: PromptInputHelpers, speculationAccept?: {...}, options?: {...}) => Promise<void>;
  onAgentSubmit?: (input: string, task: InProcessTeammateTaskState | LocalAgentTaskState, helpers: PromptInputHelpers) => Promise<void>;

  // Footer pills & navigation
  onShowMessageSelector: () => void;
  onMessageActionsEnter?: () => void;

  // MCP & agents
  mcpClients: MCPServerConnection[];

  // Pasting & images
  pastedContents: Record<number, PastedContent>;
  setPastedContents: React.Dispatch<React.SetStateAction<Record<number, PastedContent>>>;

  // Vim mode
  vimMode: VimMode;
  setVimMode: (mode: VimMode) => void;

  // Various dialogs
  showBashesDialog: string | boolean;
  setShowBashesDialog: (show: string | boolean) => void;

  // Callbacks
  onExit: () => void;
  onDismissSideQuestion?: () => void;
  isSideQuestionVisible?: boolean;

  // Internal helpers
  getToolUseContext: (messages: Message[], newMessages: Message[], abortController: AbortController, mainLoopModel: string) => ProcessUserInputContext;
  insertTextRef?: React.MutableRefObject<{ insert: (text: string) => void; setInputWithCursor: (value: string, cursor: number) => void; cursorOffset: number } | null>;
  voiceInterimRange?: { start: number; end: number } | null;
};

3.2 Command Queue Architecture

useCommandQueue hook tracks queued, non-submitted commands:

const queuedCommands = useCommandQueue();
// Returns: { [commandId]: { commandText: string; commandMode: 'prompt' | 'slash' | ... } }

Commands flow:

User types /mcp server-name → slash command detected
If agent is running → command queued (rendered in PromptInputQueuedCommands)
If agent finishes → command auto-submitted
Prevents text loss during background task transitions

3.3 Input Highlighting System

67 possible text highlights, layered by priority:

type TextHighlight = {
  start: number;
  end: number;
  color?: keyof Theme;
  inverse?: boolean;
  shimmerColor?: keyof Theme;
  dimColor?: boolean;
  priority: number;  // Higher = drawn last (on top)
};

// Priority layers:
// 1: Voice interim text (dimmed)
// 5: Slash commands, token budget, slack channels, @name mentions (blue/color)
// 8: Image chips when selected (inverted)
// 10: Rainbow colors for think/ultraplan/ultrareview/@buddy
// 15: BTW highlighting (yellow)
// 20: History search highlights (warning)

Highlight sources:

const combinedHighlights = useMemo((): TextHighlight[] => {
  // Image chip inversion (cursor at chip.start)
  // History search match highlighting
  // BTW trigger detection (side questions)
  // /command highlighting (slash commands)
  // Token budget highlighting
  // Slack channel highlighting (if MCP server available)
  // @name mentions with team member colors
  // Voice interim text dimming
  // Rainbow per-char colors for think/ultraplan/ultrareview/buddy
  return highlights;
}, [isSearchingHistory, historyQuery, ..., memberMentionHighlights, ...]);

3.4 Footer Pill Navigation System

Dynamic pill ordering based on what's visible:

const footerItems: FooterItem[] = useMemo(() => [
  tasksFooterVisible && 'tasks',
  tmuxFooterVisible && 'tmux',
  bagelFooterVisible && 'bagel',
  teamsFooterVisible && 'teams',
  bridgeFooterVisible && 'bridge',
  companionFooterVisible && 'companion'
].filter(Boolean), [tasksFooterVisible, tmuxFooterVisible, ...]);

// Selection state in AppState
const footerItemSelected = rawFooterSelection && footerItems.includes(rawFooterSelection) ? rawFooterSelection : null;

// Down/Up/Left/Right navigation with exitAtStart
function navigateFooter(delta: 1 | -1, exitAtStart = false): boolean {
  const idx = footerItemSelected ? footerItems.indexOf(footerItemSelected) : -1;
  const next = footerItems[idx + delta];
  if (next) {
    selectFooterItem(next);
    return true;
  }
  if (delta < 0 && exitAtStart) {
    selectFooterItem(null);  // Escape from pills back to input
    return true;
  }
  return false;
}

Pill visibility conditions:

const tasksFooterVisible = (runningTaskCount > 0 || coordinatorTaskCount > 0) && !shouldHideTasksFooter(tasks, showSpinnerTree);
const teamsFooterVisible = cachedTeams.length > 0;
const bridgeFooterVisible = replBridgeConnected && (replBridgeExplicit || replBridgeReconnecting);
const companionFooterVisible = !!_companion && !companionMuted;  // BUDDY feature gate

3.5 Typeahead & Suggestions Pipeline

Three suggestion sources with priority ordering:

// 1. Slash commands (hasCommand validation)
const slashCommandTriggers = useMemo(() => {
  const positions = findSlashCommandPositions(displayedValue);
  return positions.filter(pos => {
    const commandName = displayedValue.slice(pos.start + 1, pos.end);
    return hasCommand(commandName, commands);
  });
}, [displayedValue, commands]);

// 2. Slack channel mentions (via MCP server)
const knownChannelsVersion = useSyncExternalStore(subscribeKnownChannels, getKnownChannelsVersion);
const slackChannelTriggers = useMemo(
  () => hasSlackMcpServer(store.getState().mcp.clients) ? findSlackChannelPositions(displayedValue) : [],
  [displayedValue, knownChannelsVersion]
);

// 3. Team member @mentions
const memberMentionHighlights = useMemo((): TextHighlight[] => {
  if (!isAgentSwarmsEnabled()) return [];
  if (!teamContext?.teammates) return [];
  const regex = /(^|\s)@([\w-]+)/g;
  const members = teamContext.teammates;
  // ... match members by color
}, [displayedValue, teamContext]);

3.6 Image Pasting & References

Manual image paste workflow:

const nextPasteIdRef = useRef(-1);
if (nextPasteIdRef.current === -1) {
  nextPasteIdRef.current = getInitialPasteId(messages);  // Scan all messages for existing [Image #N]
}

// On image paste:
const [showPasteImage, setShowPasteImage] = useState(false);
// Getimageref → format → insert [Image #nextId] into input
const imageRefPositions = useMemo(
  () => parseReferences(displayedValue).filter(r => r.match.startsWith('[Image')).map(r => ({...})),
  [displayedValue]
);

// Snap cursor away from image chip interiors (makes them atomic, not editable char-by-char)
useEffect(() => {
  const inside = imageRefPositions.find(r => cursorOffset > r.start && cursorOffset < r.end);
  if (inside) {
    const mid = (inside.start + inside.end) / 2;
    setCursorOffset(cursorOffset < mid ? inside.start : inside.end);
  }
}, [cursorOffset, imageRefPositions]);

3.7 History Navigation (Arrow Keys)

useArrowKeyHistory hook:

const { historyQuery, setHistoryQuery, historyMatch, historyFailedMatch } = useHistorySearch(
  entry => {
    setPastedContents(entry.pastedContents);
    void onSubmit(entry.display);
  },
  input,
  trackAndSetInput,
  setCursorOffset,
  cursorOffset,
  onModeChange,
  mode,
  isSearchingHistory,
  setIsSearchingHistory,
  ...
);

Two history modes:

Arrow navigation: Up/Down cycles through full history
Search mode: Typing filters history by prefix matching; Up/Down browse matches

3.8 Agent & Teammate Integration

In-process teammates (AGENT_SWARMS feature):

const inProcessTeammates = useMemo(() => getRunningTeammatesSorted(tasks), [tasks]);
const isTeammateMode = inProcessTeammates.length > 0 || viewedTeammate !== undefined;

// Viewing a teammate overrides permission mode:
const effectiveToolPermissionContext = useMemo((): ToolPermissionContext => {
  if (viewedTeammate) {
    return { ...toolPermissionContext, mode: viewedTeammate.permissionMode };
  }
  return toolPermissionContext;
}, [viewedTeammate, toolPermissionContext]);

// Agent submission via onAgentSubmit (different from onSubmit)
if (onAgentSubmit && viewedTeammate) {
  await onAgentSubmit(input, viewedTeammate, helpers);
}

3.9 Vim Mode Toggle

isVimModeEnabled() from utils/PromptInput/utils.ts:

export function isVimModeEnabled(): boolean {
  const vimMode = getGlobalConfig().vimMode;
  return vimMode === 'on' || (vimMode === 'auto' && getTerminalName() === 'neovim');
}

VimTextInput vs TextInput:

When vimMode = 'on': render <VimTextInput />
When vimMode = 'auto': auto-detect terminal type
Else: render standard <TextInput />

Section 4: Message Rendering Pipeline

4.1 Messages Component (833 Lines)

Main message list coordinator. Handles normalization, filtering, grouping, and search highlighting.

Data flow:

Raw messages[] (AppState)
  ↓ normalizeMessages()
  ↓ filterForBriefTool() (brief-only mode)
  ↓ dropTextInBriefTurns() (drop text in turns with Brief tool)
  ↓ applyGrouping() (collapse tool uses by type)
  ↓ reorderMessagesInUI() (reorder for display)
  ↓ buildMessageLookups() (resolve references for tool results, hooks)
  ↓ NormalizedMessage[]
  ↓
VirtualMessageList (virtualization + rendering)
  ├── LogoHeader (memoized, prevents seenDirtyChild cascade)
  └── MessageRow[] (per message)
      ├── MessageActionsSelectedContext (selected message in actions nav mode)
      └── Type-specific renderer dispatch

4.2 Normalization & Filtering

filterForBriefTool (lines 93-158):

Brief-only mode shows ONLY Brief tool_use blocks + tool_results + real user input:

export function filterForBriefTool<T extends {...}>(messages: T[], briefToolNames: string[]): T[] {
  const nameSet = new Set(briefToolNames);
  const briefToolUseIDs = new Set<string>();
  return messages.filter(msg => {
    if (msg.type === 'system') return msg.subtype !== 'api_metrics';
    const block = msg.message?.content[0];
    if (msg.type === 'assistant') {
      if (msg.isApiErrorMessage) return true;  // Keep API errors (auth, rate limits)
      if (block?.type === 'tool_use' && nameSet.has(block.name)) {
        briefToolUseIDs.add(block.id);
        return true;
      }
      return false;  // Drop assistant text (model responsible for calling Brief)
    }
    if (msg.type === 'user') {
      if (block?.type === 'tool_result') return briefToolUseIDs.has(block.tool_use_id);
      return !msg.isMeta;  // Real user input only
    }
    // ...
  });
}

Why: In Brief-only mode, if the model forgets to call Brief, the user sees nothing. That's intentional — the model is responsible for the workflow.

4.3 dropTextInBriefTurns (lines 169-200)

Full-transcript companion: When Brief is in use, drop assistant text blocks (model's explanation) to avoid redundancy with SendUserMessage content:

export function dropTextInBriefTurns<T extends {...}>(messages: T[], briefToolNames: string[]): T[] {
  const nameSet = new Set(briefToolNames);

  // First pass: find which turns contain a Brief tool_use
  const turnsWithBrief = new Set<number>();
  const textIndexToTurn: number[] = [];
  let turn = 0;
  for (let i = 0; i < messages.length; i++) {
    const msg = messages[i]!;
    const block = msg.message?.content[0];
    if (msg.type === 'user' && block?.type !== 'tool_result' && !msg.isMeta) {
      turn++;
      continue;
    }
    if (msg.type === 'assistant') {
      if (block?.type === 'text') {
        textIndexToTurn[i] = turn;
      } else if (block?.type === 'tool_use' && nameSet.has(block.name)) {
        turnsWithBrief.add(turn);
      }
    }
  }

  // Second pass: drop text in turnsWithBrief
  return messages.filter((msg, i) => !(msg.type === 'assistant' && textIndexToTurn[i] !== undefined && turnsWithBrief.has(textIndexToTurn[i])));
}

4.4 Message Lookups & Resolution

buildMessageLookups creates indices for fast access:

const lookups = buildMessageLookups(normalizedMessages);
// Returns: {
//   byId: Map<UUID, Message>,
//   byToolUseId: Map<toolUseId, { message: Message; index: number }>,
//   lastUserIndex: number,
//   unresolvedHooks: Set<hookId>,
// }

const hasUnresolved = hasUnresolvedHooksFromLookup(lookups);

Used by MessageRow to:

Resolve tool_result blocks → their corresponding tool_use
Track unresolved hooks (pending tool calls)
Validate message structure

4.5 VirtualMessageList (1,081 Lines)

Virtualization coordinator for large message streams:

export function VirtualMessageList({
  messages,
  jumpHandle,
  ...
}: Props) {
  const containerRef = useRef<ScrollBoxHandle>(null);
  const firstVisibleIndex = useRef(0);
  const lastVisibleIndex = useRef(0);

  // Virtual scrolling logic:
  // - Render only messages in viewport + buffer (typically -2/+2 pages)
  // - As user scrolls, recalculate visible range
  // - On scroll-to-bottom, stick to latest message

  return (
    <ScrollBox ref={containerRef} onScroll={handleScroll}>
      {/* Render messages[firstVisibleIndex..lastVisibleIndex] */}
      {visibleMessages.map((msg, idx) => (
        <MessageRow key={msg.id} message={msg} />
      ))}
    </ScrollBox>
  );
}

Jump handle for search:

export type JumpHandle = {
  jumpToMessage: (messageId: UUID) => void;
  jumpToBottom: () => void;
  jumpToOffset: (percentage: number) => void;
};

// Used by GlobalSearchDialog to jump to matching message

4.6 MessageRow Dispatch Logic

MessageRow (1,020+ lines) dispatches to type-specific renderers:

export function MessageRow({
  message,
  isSelected,
  renderableMessage,
  ...
}: Props) {
  const type = message.type;
  const block = message.message?.content[0];

  if (type === 'user') {
    if (block?.type === 'tool_result') return <ToolResultMessage />;
    return <UserTextMessage />;
  }

  if (type === 'assistant') {
    if (isAssistantThinking) return <AssistantThinkingMessage />;
    if (block?.type === 'text') return <StreamingMarkdown />;
    if (block?.type === 'tool_use') return <ToolUseMessage />;
  }

  if (type === 'system') {
    return <SystemTextMessage />;
  }

  if (type === 'attachment') {
    const att = message.attachment;
    if (att?.type === 'queued_command') return <QueuedCommandAttachment />;
    if (att?.type === 'pdf_file') return <PdfAttachment />;
    // ...
  }

  return null;
}

4.7 Message Actions (Read-Only Cursor Navigation)

InVirtualListContext + MessageActionsSelectedContext:

type MessageActionsState = {
  isActive: boolean;
  selectedMessageId: UUID | null;
  selectedContentIndex: number;  // For multi-block messages
};

// Keybinding: Shift+↑ enters message actions mode
// j/k navigate between messages
// l/h navigate content within message
// g/p/c open specific actions (generate, prompt, copy)

Section 5: Permission UI System (51+ Components)

5.1 Permission Architecture

Three-tier permission system:

1. ToolPermissionContext (AppState)
   ├── mode: 'auto' | 'manual' | 'bypass'
   ├── isBypassPermissionsModeAvailable: boolean
   └── toolPermissions: ToolPermissionState[]

2. PermissionRule[] (persisted, rule-based)
   ├── ruleId
   ├── pattern (tool name wildcard)
   ├── action: 'allow' | 'deny' | 'ask'
   ├── reason (user-provided justification)
   └── scope: 'once' | 'session' | 'permanent'

3. Runtime Decision Flow
   ├── Check toolPermissionContext.mode
   ├── Evaluate PermissionRule[] for match
   ├── Show PermissionRequest UI if needed
   └── Execute or reject tool

5.2 Component Hierarchy

permissions/PermissionRuleList.tsx (1,178 lines):

Master rule management interface:

type Props = {
  rules: PermissionRule[];
  onAddRule: (rule: PermissionRule) => void;
  onDeleteRule: (ruleId: string) => void;
  onUpdateRule: (rule: PermissionRule) => void;
  onClose: () => void;
};

Renders:

Rule list with search/filter
Add new rule dialog
Edit rule inline
Delete with confirmation
Scope selector (once/session/permanent)

Key permission dialogs:

Component	Purpose
`PermissionRequest.tsx`	Generic ask-to-confirm dialog
`ExitPlanModePermissionRequest.tsx` (767 lines)	Confirm exit from mode
`PermissionRuleList.tsx` (1,178 lines)	Rule management
`PermissionExplanation.tsx`	Explain why tool needs permission
`ToolUseConfirm.tsx`	Confirm specific tool use
`AutoModeOptInDialog.tsx`	Opt in to auto mode

5.3 Permission Decision Logic

File: utils/permissions/permissionSetup.ts

export function getNextPermissionMode(
  current: PermissionMode,
  isBypassAvailable: boolean
): PermissionMode {
  // Cycle: auto → manual → (bypass?) → auto
  const modes: PermissionMode[] = ['auto', 'manual'];
  if (isBypassAvailable) modes.push('bypass');

  const idx = modes.indexOf(current);
  return modes[(idx + 1) % modes.length];
}

export function cyclePermissionMode(
  setAppState: (f: (prev: AppState) => AppState) => void,
  isBypassAvailable: boolean
): void {
  setAppState(prev => ({
    ...prev,
    toolPermissionContext: {
      ...prev.toolPermissionContext,
      mode: getNextPermissionMode(prev.toolPermissionContext.mode, isBypassAvailable)
    }
  }));
}

Section 6: Modal & Dialog System

6.1 OverlayContext & Focus Management

File: context/overlayContext.ts

type OverlayState = {
  activeOverlay: string | null;  // Dialog name
  priorityStack: string[];  // Z-order for nested dialogs
};

export function useIsModalOverlayActive(): boolean {
  return useContext(OverlayContext)?.activeOverlay !== null;
}

export function useShowDialog(dialogName: string) {
  const dispatch = useContext(OverlayDispatch);
  return {
    show: () => dispatch({ type: 'SHOW', dialog: dialogName }),
    hide: () => dispatch({ type: 'HIDE', dialog: dialogName }),
  };
}

Purpose: Prevent keyboard navigation (arrow keys, enter) from leaking into TextInput when a dialog is open.

6.2 Dialog Component (Design System)

design-system/Dialog.tsx:

export function Dialog({
  title,
  content,
  footer,
  width = 80,
  height = 'auto',
  onClose,
  focusable = true,
}: Props): React.ReactNode {
  return (
    <Box borderStyle="round" borderColor="blue" paddingX={1} paddingY={1}>
      <Box marginBottom={1}>{title}</Box>
      <Box>{content}</Box>
      <Box marginTop={1}>{footer}</Box>
    </Box>
  );
}

Used by all 51+ permission dialogs, settings, logs, etc.

6.3 Modal Stacking

Dialogs are stacked in AppState.overlayStack:

overlayStack: Array<{
  dialogName: string;
  props: Record<string, unknown>;
}>

Example nesting:

GlobalSearchDialog opens
User clicks "open in log selector"
LogSelector opens (on top of search)
User closes log selector
GlobalSearchDialog is active again

Section 7: Settings Architecture (Config.tsx, 1,821 Lines)

7.1 Settings Tabs

Config.tsx renders a tabbed interface with search:

type SubMenu =
  | 'Theme'
  | 'Model'
  | 'TeammateModel'
  | 'ExternalIncludes'
  | 'OutputStyle'
  | 'ChannelDowngrade'
  | 'Language'
  | 'EnableAutoUpdates';

Main settings (searchable):

const settingsItems: Setting[] = [
  // Global settings (saved to ~/.config/claude-code/config.json)
  {
    id: 'autoCompactEnabled',
    label: 'Auto-compact',
    value: globalConfig.autoCompactEnabled,
    type: 'boolean',
    onChange(v) {
      saveGlobalConfig(current => ({ ...current, autoCompactEnabled: v }));
      setGlobalConfig(getGlobalConfig());  // Refresh from disk
      logEvent('tengu_auto_compact_setting_changed', { enabled: v });
    }
  },

  // Local settings (project-specific)
  {
    id: 'spinnerTipsEnabled',
    label: 'Show tips',
    value: settingsData?.spinnerTipsEnabled ?? true,
    type: 'boolean',
    onChange(v) {
      updateSettingsForSource('localSettings', { spinnerTipsEnabled: v });
      setSettingsData(prev => ({ ...prev, spinnerTipsEnabled: v }));
    }
  },

  // Runtime AppState (not persisted)
  {
    id: 'verbose',
    label: 'Verbose output',
    value: verbose,
    type: 'boolean',
    onChange(v) {
      setAppState(prev => ({ ...prev, verbose: v }));
      saveGlobalConfig(current => ({ ...current, verbose: v }));
    }
  },
];

7.2 Managed Enums (Custom Components)

Some settings open sub-dialogs instead of inline toggles:

// Model picker opens ModelPicker component
{
  id: 'model',
  label: 'Model',
  value: modelDisplayString(mainLoopModel),
  type: 'managedEnum',
  onChange(v) {
    onChangeMainModelConfig(v);  // Custom handler that updates AppState + logs event
  }
}

// Theme picker opens ThemePicker component
{
  id: 'theme',
  label: 'Theme',
  value: themeSetting,
  type: 'managedEnum',
  onChange(v) {
    setTheme(v);  // Ink.js theme context
    saveGlobalConfig(current => ({ ...current, theme: v }));
  }
}

7.3 Search Integration

Settings support live search with highlighting:

const {
  query: searchQuery,
  setQuery: setSearchQuery,
  cursorOffset: searchCursorOffset
} = useSearchInput({
  isActive: isSearchMode && showSubmenu === null && !headerFocused,
  onExit: () => setIsSearchMode(false),
  onExitUp: focusHeader,
  passthroughCtrlKeys: ['c', 'd']  // Let Settings handle Ctrl+C/D
});

// Filter settings by searchQuery
const filtered = settingsItems.filter(s =>
  s.label.toLowerCase().includes(searchQuery.toLowerCase())
);

Section 8: Scroll & Input Handling (ScrollKeybindingHandler, 1,011 Lines)

8.1 Scroll Acceleration Curves

Different terminal types have different scroll physics. ScrollKeybindingHandler normalizes them:

export type ScrollAccelerationProfile = 'native' | 'xterm' | 'ghostty';

const SCROLL_CONFIG: Record<ScrollAccelerationProfile, ScrollCurve> = {
  native: {
    // Kitty, iTerm2: scrollback is full-screen lines
    lineHeight: Math.floor(terminalRows * 0.95),
    acceleration: 1.2,
    maxVelocity: 10
  },
  xterm: {
    // xterm.js: smaller scroll increments
    lineHeight: 3,
    acceleration: 1.05,
    maxVelocity: 5
  },
  ghostty: {
    // Ghostty: hybrid approach
    lineHeight: Math.floor(terminalRows * 0.5),
    acceleration: 1.1,
    maxVelocity: 8
  }
};

8.2 Trackpad vs Mouse Detection

function isTrackpadEvent(wheelEvent: WheelEvent): boolean {
  // Trackpad: smooth continuous, fractional deltaY
  // Mouse: discrete jumps, integral deltaY
  // Heuristic: deltaY % 1 !== 0 → trackpad
  return wheelEvent.deltaY % 1 !== 0;
}

// Adjust curve based on device:
const curve = isTrackpad ? TRACKPAD_CURVE : MOUSE_CURVE;

8.3 Keybinding Integration

ScrollKeybindingHandler registers keybindings with KeybindingContext:

useKeybinding('shift+pageup', () => scrollUp(10));
useKeybinding('shift+pagedown', () => scrollDown(10));
useKeybinding('shift+home', () => jumpToTop());
useKeybinding('shift+end', () => jumpToBottom());
useKeybinding('ctrl+u', () => scrollUp(Math.ceil(terminalRows / 2)));
useKeybinding('ctrl+d', () => scrollDown(Math.ceil(terminalRows / 2)));

Section 9: Performance Patterns

9.1 React.memo & Memoization Strategy

Aggressive memoization of expensive components:

// LogoHeader prevents cascade dirty-flag in long sessions
const LogoHeader = React.memo(function LogoHeader({ agentDefinitions }) {
  // When LogoHeader doesn't remount, renderChildren's seenDirtyChild
  // doesn't cascade, preventing ALL subsequent MessageRows from re-rendering.
  // In 2800-message sessions, this saves ~150K writes/frame.
  return (
    <OffscreenFreeze>
      <Box flexDirection="column" gap={1}>
        <LogoV2 />
        <React.Suspense fallback={null}>
          <StatusNotices agentDefinitions={agentDefinitions} />
        </React.Suspense>
      </Box>
    </OffscreenFreeze>
  );
}, (prevProps, nextProps) => prevProps.agentDefinitions === nextProps.agentDefinitions);

MessageRow memoization:

export const MessageRow = React.memo(function MessageRow(props: Props) {
  // Memoized per-message. Only re-render if message object reference changes
  // (not just content inside message).
}, (prev, next) => {
  return (
    prev.message === next.message &&
    prev.isSelected === next.isSelected &&
    prev.renderableMessage === next.renderableMessage
  );
});

9.2 useMemo Dependencies

Carefully managed dependency arrays to prevent unnecessary recalculations:

// BAD: Recalculates on every keystroke
const imageRefs = useMemo(
  () => parseReferences(input).filter(r => r.match.startsWith('[Image')),
  [input, displayedValue, historyMatch, ...]  // Too many deps
);

// GOOD: Only depends on actual trigger
const imageRefs = useMemo(
  () => parseReferences(displayedValue).filter(r => r.match.startsWith('[Image')),
  [displayedValue]  // Single, focused dep
);

9.3 React Compiler Annotations (_c)

Extensive use of _c annotations for compiler optimization:

function Config({ onClose, context, setTabsHidden }: Props) {
  const $ = _c(13);  // Array cache for memoized values
  // ...
  let t1;
  if ($[0] !== initialState || $[1] !== onChangeAppState) {
    t1 = () => createStore(initialState ?? getDefaultAppState(), onChangeAppState);
    $[0] = initialState;
    $[1] = onChangeAppState;
    $[2] = t1;
  } else {
    t1 = $[2];
  }
  // Compiler auto-memoizes JSX when inputs haven't changed
}

Purpose: React 19 compiler automatically prevents re-renders when input values are identical.

9.4 Virtual Scrolling

VirtualMessageList only renders visible messages + buffer:

// Keep messages in viewport + 2 pages above/below
const bufferSize = Math.ceil(terminalRows * 2);
const firstVisible = Math.max(0, firstVisibleIndex - bufferSize);
const lastVisible = Math.min(messages.length, lastVisibleIndex + bufferSize);

return visibleMessages.slice(firstVisible, lastVisible).map((msg, idx) => (
  <MessageRow key={msg.id} message={msg} />
));

Result: 2800-message session renders ~20-30 components at a time, not 2800.

9.5 Lazy Component Loading

Feature-gated conditional requires to avoid loading unnecessary code:

// Dead code elimination: voice context is ant-only
const VoiceProvider = feature('VOICE_MODE') ?
  require('../context/voice.js').VoiceProvider :
  ({ children }) => children;

// Brief tool is kairos-only
const BRIEF_TOOL_NAME = feature('KAIROS') || feature('KAIROS_BRIEF') ?
  require('../tools/BriefTool/prompt.js').BRIEF_TOOL_NAME :
  null;

// Proactive mode
const proactiveModule = feature('PROACTIVE') || feature('KAIROS') ?
  require('../proactive/index.js') :
  null;

Benefit: External (non-ant) builds don't include voice/proactive code at all—bun's bundle() strips it.

Section 10: Design System (Primitives)

10.1 Core Primitives

design-system/ directory:

Component	Purpose	Lines
Dialog.tsx	Modal wrapper	~100
Tabs.tsx	Tabbed navigation	~150
Pane.tsx	Content area (scrollable)	~80
SearchBox.tsx	Search input	~60
KeyboardShortcutHint.tsx	Keybinding display	~40
Divider.tsx	Visual separator	~20
Byline.tsx	Attribution text	~30

Ink.js re-exports:

export { Box, Text, Spacer } from '../../ink.js';
export type { ClickEvent, Key } from '../../ink.js';

10.2 Dialog Composition

Generic dialog pattern:

<Dialog
  title={<Text bold>Settings</Text>}
  content={
    <Tabs
      tabs={['General', 'Model', 'Permissions']}
      onSelectTab={setActiveTab}
    >
      {activeTab === 0 && <GeneralSettings />}
      {activeTab === 1 && <ModelSettings />}
      {activeTab === 2 && <PermissionSettings />}
    </Tabs>
  }
  footer={
    <Box gap={2}>
      <Text onPress={onClose} color="cyan">Esc</Text>
      <Text>to close</Text>
    </Box>
  }
/>

Section 11: Error Handling & Boundaries

11.1 SentryErrorBoundary Placement

Top-level error capture:

export function REPL() {
  return (
    <SentryErrorBoundary
      fallback={<ErrorScreen error="Unexpected error" />}
      showDialog
    >
      <FullscreenLayout>
        <Messages />
        <PromptInput />
      </FullscreenLayout>
    </SentryErrorBoundary>
  );
}

11.2 Graceful Degradation

Suspense boundaries for async components:

<React.Suspense fallback={null}>
  <StatusNotices agentDefinitions={agentDefinitions} />
</React.Suspense>

nullish coalescing for optional features:

const showAutoInDefaultModePicker = feature('TRANSCRIPT_CLASSIFIER')
  ? hasAutoModeOptInAnySource() || getAutoModeEnabledState() === 'enabled'
  : false;

Section 12: Key Constants & Context Providers

12.1 Input Modes

type PromptInputMode = 'raw' | 'message' | 'api_metrics';

const PROMPT_FOOTER_LINES = 5;
const MIN_INPUT_VIEWPORT_LINES = 3;
const PASTE_THRESHOLD = 5000;  // Auto-trigger image paste UI if >5KB
const FOOTER_TEMPORARY_STATUS_TIMEOUT = 2000;

12.2 Command Types

enum CommandMode {
  'prompt' = 'user typed in PromptInput',
  'slash' = '/command detected',
  'task-notification' = 'queued from background task',
  'immediate-command' = 'direct invocation (e.g., /mcp)'
}

12.3 Event Names (Analytics)

logEvent('tengu_config_model_changed', { from_model, to_model });
logEvent('tengu_auto_compact_setting_changed', { enabled });
logEvent('tengu_tips_setting_changed', { enabled });
logEvent('tengu_permission_mode_changed', { from_mode, to_mode });
logEvent('tengu_input_submitted', { command_type, effort_level });

12.4 Context Providers Summary

Name	Location	Purpose
AppStoreContext	state/AppState.tsx	Global state store access
HasAppStateContext	state/AppState.tsx	Prevent nesting
OverlayContext	context/overlayContext.ts	Modal active state
PromptOverlayContext	context/promptOverlayContext.ts	Prompt-specific overlays
ModalContext	context/modalContext.ts	Inside-modal detection
KeybindingContext	keybindings/KeybindingContext.ts	Shortcut registry
FpsMetricsContext	context/fpsMetrics.ts	Frame timing
StatsContext	context/stats.ts	Analytics events
MailboxContext	context/mailbox.ts	Team messaging (AGENT_SWARMS)
VoiceContext	context/voice.ts	Voice input (VOICE_MODE, feature-gated)
ThemeContext	ink.js	Terminal colors

Section 13: Data Flow Diagrams

13.1 User Input to Command Execution

[User types in TextInput]
  ↓
onInputChange(value) [PromptInput prop]
  ↓
Parent component (main.tsx) updates AppState:
  setAppState(prev => ({ ...prev, input: value }))
  ↓
[Triggers]
├── useAppState(s => s.input) subscribers re-render
├── Input highlighting recalculation
├── Command suggestion regeneration
└── Prompt suggestion check

[User presses Enter]
  ↓
onSubmit(input, helpers) [PromptInput callback]
  ↓
[main.tsx query handler]
├── Normalization & validation
├── Tool permission check (auto/manual/bypass)
├── Create new messages (user message + assistant message placeholder)
├── Append to AppState.messages
└── Start agent loop (query.ts)

[Agent loop execution]
  ↓
[Tools are called]
  ↓
[Tool results appended to messages]
  ↓
AppState.messages updated
  ↓
VirtualMessageList re-renders visible messages

13.2 Teammate/Swarm Message Flow

[Leader input "Hey @alice, do X"]
  ↓
Parsed @mention → teammate name
  ↓
writeToMailbox(teammateName, { prompt: "do X", from: "leader" })
  ↓
[Teammate background task checks mailbox]
  ↓
MailboxProvider subscription notifies task
  ↓
[Teammate executes its own query loop with "do X" as input]
  ↓
[Results sent back via mailbox]
  ↓
Leader sees teammate's messages in transcript
  ↓
Leader can @mention response in next turn

13.3 Permission Mode Cycling

[User toggles permission mode via keyboard]
  ↓
useKeybinding('ctrl+p', () => cyclePermissionMode(...))
  ↓
getNextPermissionMode('auto') → 'manual' (if bypass unavailable)
                               → 'bypass' (if available)
                               → 'auto' (cycle)
  ↓
setAppState(prev => ({
  ...prev,
  toolPermissionContext: { ...prev.toolPermissionContext, mode: next }
}))
  ↓
[All tool permission checks now use new mode]
├── 'auto': tools execute without asking
├── 'manual': show PermissionRequest dialog before each tool
└── 'bypass': all permissions denied (read-only mode)

Section 14: Key Design Decisions & Trade-Offs

14.1 Custom Store vs Redux

Decision: Implement Zustand-like store with useSyncExternalStore

Why:

Terminal rendering must be reactive but NOT batched
Redux's async thunk middleware adds unnecessary complexity
Custom store is ~200 lines, works seamlessly with React 18
Perfect for hand-tuned performance (memoization, selectors)

Trade-off: No Redux DevTools, but minimal use case (single-page REPL, not complex SPA)

14.2 Selective Rendering via Selectors

Decision: Never create new objects in selectors; only select existing references

// GOOD: Select sub-object reference
const promptSuggestion = useAppState(s => s.promptSuggestion);

// BAD: Creates new object every render
const { text } = useAppState(s => ({ text: s.promptSuggestion.text }));

Why: Object.is comparison is used for subscription changes. Creating new objects = always different = always re-render.

Trade-off: Requires componentized sub-state (promptSuggestion, speculation, etc.) instead of flat state.

14.3 Virtual Scrolling for Messages

Decision: Only render visible messages + buffer

Why: 2800-message session with all MessageRows mounted = ~150K+ writes/frame when cascading dirty.

Trade-off: Scroll position must be carefully managed (useRef tracking). Jump-to-message requires index lookup.

14.4 Feature Gating with bun:bundle feature()

Decision: Use compile-time feature gates instead of runtime flags

const VoiceProvider = feature('VOICE_MODE') ? require(...) : PassthroughProvider;

Why:

External (non-ant) builds are smaller (voice code not included)
Clear separation between ant-only and public features
bun's bundler eliminates dead code at build time

Trade-off: Feature flags must be known at build time (env variables or build.js manifest).

14.5 Permanent Stash (Pause/Resume Input)

Decision: Allow users to stash current input and resume later

Why: When a background task drains user input mid-turn, the user's in-flight text isn't lost—it's stashed and can be resumed.

Trade-off: Adds complexity (pastedContents lookup, cursorOffset tracking), but critical for non-local agent workflows.

14.6 Three-Tier Settings

Decision: GlobalConfig (user-level) + LocalSettings (project) + AppState (runtime)

Why:

GlobalConfig: shared across all projects (theme, vim mode)
LocalSettings: per-project (bridge enabled, language)
AppState: temporary session-level (mainLoopModel override)

Trade-off: Requires reconciliation logic on startup (mergeSettings), but enables flexible override hierarchy.

Section 15: Security & Attack Vectors (Secondary Addendum)

15.1 Potential Vulnerabilities

1. Tool Permission Bypass:

Attack: Craft prompt to get model to call tools agent doesn't have permission for
Mitigation: Permission check happens before tool execution, not by tool. Model can't override.

2. Mailbox Spoofing (Teammates):

Attack: Inject false task results via mailbox
Mitigation: Mailbox is in-process only. No network exposure.

3. MCP Server Code Injection:

Attack: Malicious MCP server in PATH sends arbitrary commands
Mitigation: MCP servers are user-provided (in ~/agent-tools/). User is responsible.

4. History Leak:

Attack: Access ~/.cache/claude-code/history.json
Mitigation: History stored in user's home dir. Standard Unix permissions apply.

5. Image Paste Exploitation:

Attack: Paste large file → OOM
Mitigation: PASTE_THRESHOLD (5000 bytes) prevents auto-upload of large files. User must explicitly opt-in.

15.2 Recommendations

Audit all feature-gated code paths (feature() gates)
Validate all MCP server inputs
Sanitize all tool permission rules
Monitor mailbox message sizes (DoS via huge messages)

Appendix: File Size Reference

Tier 1 (Read Completely)

PromptInput/PromptInput.tsx: 2,338 lines — Command queue, typeahead, agent integration, buddy system
Settings/Config.tsx: 1,821 lines — Settings tabs, search, validation
LogSelector.tsx: 1,574 lines — Session picker with history
Stats.tsx: 1,227 lines — Usage heatmap visualization
permissions/PermissionRuleList.tsx: 1,178 lines — Rule management
mcp/ElicitationDialog.tsx: 1,168 lines — MCP form rendering
VirtualMessageList.tsx: 1,081 lines — Virtual scrolling coordinator
ScrollKeybindingHandler.tsx: 1,011 lines — Scroll physics & keybindings

Tier 2 (First 200 lines + key sections)

tasks/RemoteSessionDetailDialog.tsx: 903 lines
Messages.tsx: 833 lines
MessageSelector.tsx: 830 lines
messages/SystemTextMessage.tsx: 826 lines
agents/AgentsMenu.tsx: 799 lines
permissions/ExitPlanModePermissionRequest.tsx: 767 lines
teams/TeamsDialog.tsx: 714 lines
CustomSelect/select.tsx: 689 lines
tasks/BackgroundTasksDialog.tsx: 651 lines
mcp/MCPRemoteServerMenu.tsx: 648 lines
PromptInput/PromptInputFooterLeftSide.tsx: 598 lines

Design System

Dialog.tsx: ~100 lines
Tabs.tsx: ~150 lines
Pane.tsx: ~80 lines
SearchBox.tsx: ~60 lines
KeyboardShortcutHint.tsx: ~40 lines

Conclusion

Claude Code v2.1.88's architecture is a sophisticated, highly-optimized React application engineered for responsive terminal interaction. Key engineering achievements:

State-centric design via custom Zustand-like store with fine-grained selectors
Extreme performance optimization through memoization, virtual scrolling, and React Compiler annotations
Permission system with 51+ dedicated components for nuanced tool control
Real-time interactivity via keybinding context and event-driven architecture
Multi-agent coordination using in-process mailbox pattern for teammate communication
Modular permission rules enabling rule-based tool access control

The architecture prioritizes correctness over cleverness, with clear separation of concerns, exhaustive error handling, and graceful degradation when features are unavailable. The codebase is production-hardened for 2800+ message sessions without UI lag or CPU pegging.

FilesExpand file tree

component-architecture-deep-dive.md

Latest commit

History

component-architecture-deep-dive.md

File metadata and controls

Claude Code v2.1.88 React Component Architecture Deep-Dive

Executive Summary

Section 1: Component Hierarchy & Topology

1.1 Root Component Composition

1.2 Main Screen Structure (REPL)

1.3 Component Classification

Section 2: State Management Architecture

2.1 AppState Store Design

2.2 Store Implementation

2.3 Subscription Patterns

2.4 AppStateProvider Nesting Guards

2.5 Settings & Configuration Layers

2.6 Context Providers (Beyond AppState)

Section 3: PromptInput Deep-Dive (2,338 Lines)

3.1 PromptInput Props Interface

3.2 Command Queue Architecture

3.3 Input Highlighting System

3.4 Footer Pill Navigation System

3.5 Typeahead & Suggestions Pipeline

3.6 Image Pasting & References

3.7 History Navigation (Arrow Keys)

3.8 Agent & Teammate Integration

3.9 Vim Mode Toggle

Section 4: Message Rendering Pipeline

4.1 Messages Component (833 Lines)

4.2 Normalization & Filtering

4.3 dropTextInBriefTurns (lines 169-200)

4.4 Message Lookups & Resolution

4.5 VirtualMessageList (1,081 Lines)

4.6 MessageRow Dispatch Logic

4.7 Message Actions (Read-Only Cursor Navigation)

Section 5: Permission UI System (51+ Components)

5.1 Permission Architecture

5.2 Component Hierarchy

5.3 Permission Decision Logic

Section 6: Modal & Dialog System

6.1 OverlayContext & Focus Management

6.2 Dialog Component (Design System)

6.3 Modal Stacking

Section 7: Settings Architecture (Config.tsx, 1,821 Lines)

7.1 Settings Tabs

7.2 Managed Enums (Custom Components)

7.3 Search Integration

Section 8: Scroll & Input Handling (ScrollKeybindingHandler, 1,011 Lines)

8.1 Scroll Acceleration Curves

8.2 Trackpad vs Mouse Detection

8.3 Keybinding Integration

Section 9: Performance Patterns

9.1 React.memo & Memoization Strategy

9.2 useMemo Dependencies

9.3 React Compiler Annotations (_c)

9.4 Virtual Scrolling

9.5 Lazy Component Loading

Section 10: Design System (Primitives)

10.1 Core Primitives

10.2 Dialog Composition

Section 11: Error Handling & Boundaries

11.1 SentryErrorBoundary Placement

11.2 Graceful Degradation

Section 12: Key Constants & Context Providers

12.1 Input Modes

12.2 Command Types

12.3 Event Names (Analytics)

12.4 Context Providers Summary

Section 13: Data Flow Diagrams

13.1 User Input to Command Execution

13.2 Teammate/Swarm Message Flow

13.3 Permission Mode Cycling

Section 14: Key Design Decisions & Trade-Offs

14.1 Custom Store vs Redux

14.2 Selective Rendering via Selectors

14.3 Virtual Scrolling for Messages

14.4 Feature Gating with bun:bundle feature()

14.5 Permanent Stash (Pause/Resume Input)