State Management

Most React apps reach for a library — Redux, Zustand, Jotai — when their state needs to span the component tree. Claude Code builds its own store from scratch in 35 lines of TypeScript and plugs it directly into React's built-in useSyncExternalStore hook. Understanding why, and what sits on top, is essential for navigating any non-trivial change to the REPL.

The architecture has three distinct layers:

The entire store primitive is in state/store.ts. Three concepts, 35 lines:

type Listener = () => void
type OnChange<T> = (args: { newState: T; oldState: T }) => void

export type Store<T> = {
  getState: () => T
  setState: (updater: (prev: T) => T) => void
  subscribe: (listener: Listener) => () => void
}

export function createStore<T>(
  initialState: T,
  onChange?: OnChange<T>,
): Store<T> {
  let state = initialState
  const listeners = new Set<Listener>()

  return {
    getState: () => state,

    setState: (updater) => {
      const prev = state
      const next = updater(prev)
      if (Object.is(next, prev)) return   // bail if no change
      state = next
      onChange?.({ newState: next, oldState: prev })  // side-effect hook
      for (const listener of listeners) listener()  // notify React
    },

    subscribe: (listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)  // unsubscribe
    },
  }
}

Why not useState / useReducer?

React's own hooks tie state lifetime to a component tree. Claude Code needs state that is readable from non-React code: headless mode, the SDK print layer, per-process teammate sessions, the onChangeAppState side-effect chain. A plain JS object with a Set of listeners costs nothing to pass around outside React.

Why not Zustand / Jotai?

Zero additional bundle dependency. The interface Claude Code actually needs — getState, setState, subscribe — maps exactly onto what useSyncExternalStore requires. There is nothing left to buy.

// From AppState.tsx — the full useAppState implementation:
export function useAppState(selector) {
  const store = useAppStore()
  const get = () => selector(store.getState())
  return useSyncExternalStore(store.subscribe, get, get)
}

AppState is defined in state/AppStateStore.ts. It is enormous — over 90 distinct fields — but it has clear internal structure. The type is DeepImmutable<{...}> for the serializable portion, with a small number of fields that escape the immutability wrapper (function types, Map, Set) explicitly listed after the &.

The fields break down into six logical categories:

Selected field reference

export type AppState = DeepImmutable<{
  settings: SettingsJson
  verbose: boolean
  // ... ~60 serializable fields ...
}> & {
  // Excluded from DeepImmutable — contain function types
  tasks: { [taskId: string]: TaskState }
  agentNameRegistry: Map<string, AgentId>
  mcp: { clients: MCPServerConnection[]; /* ... */ }
  // ...
}

type SpeculationState =
  | { status: 'idle' }
  | {
      status: 'active'
      id: string
      abort: () => void
      startTime: number
      messagesRef: { current: Message[] }     // mutable ref — no array copy per msg
      writtenPathsRef: { current: Set<string> } // relative paths in overlay
      boundary: CompletionBoundary | null
      suggestionLength: number
      toolUseCount: number
      isPipelined: boolean
      contextRef: { current: REPLHookContext }
      pipelinedSuggestion?: { text: string; promptId: ...; generationRequestId: ... } | null
    }

The second argument to createStore is an optional onChange callback. Claude Code passes onChangeAppState here — a single function that fires on every state transition and diffs relevant fields to drive side effects.

The current diff blocks in onChangeAppState:

export function onChangeAppState({ newState, oldState }) {

  // 1. Permission mode — sync to CCR external_metadata + SDK status stream
  const prevMode = oldState.toolPermissionContext.mode
  const newMode = newState.toolPermissionContext.mode
  if (prevMode !== newMode) {
    const prevExternal = toExternalPermissionMode(prevMode)
    const newExternal  = toExternalPermissionMode(newMode)
    if (prevExternal !== newExternal) {
      // Guard: internal-only modes (bubble, ungated-auto) don't pollute CCR.
      // is_ultraplan_mode set null per RFC 7396 (removes key from JSON patch).
      notifySessionMetadataChanged({ permission_mode: newExternal, ... })
    }
    notifyPermissionModeChanged(newMode)  // SDK channel — passes raw mode
  }

  // 2. mainLoopModel — persist to settings + bootstrap override
  if (newState.mainLoopModel !== oldState.mainLoopModel) {
    if (newState.mainLoopModel === null) {
      updateSettingsForSource('userSettings', { model: undefined })
      setMainLoopModelOverride(null)
    } else {
      updateSettingsForSource('userSettings', { model: newState.mainLoopModel })
      setMainLoopModelOverride(newState.mainLoopModel)
    }
  }

  // 3. expandedView — persist to globalConfig (showExpandedTodos / showSpinnerTree)
  if (newState.expandedView !== oldState.expandedView) {
    saveGlobalConfig(current => ({
      ...current,
      showExpandedTodos: newState.expandedView === 'tasks',
      showSpinnerTree:   newState.expandedView === 'teammates',
    }))
  }

  // 4. verbose — persist to globalConfig
  if (newState.verbose !== oldState.verbose) {
    saveGlobalConfig(current => ({ ...current, verbose: newState.verbose }))
  }

  // 5. tungstenPanelVisible — ant-only, persist to globalConfig
  if (process.env.USER_TYPE === 'ant' && newState.tungstenPanelVisible !== oldState.tungstenPanelVisible) {
    saveGlobalConfig(current => ({ ...current, tungstenPanelVisible: newState.tungstenPanelVisible }))
  }

  // 6. settings — clear auth caches + re-apply env vars
  if (newState.settings !== oldState.settings) {
    clearApiKeyHelperCache()
    clearAwsCredentialsCache()
    clearGcpCredentialsCache()
    if (newState.settings.env !== oldState.settings.env) {
      applyConfigEnvironmentVariables()
    }
  }
}

The externalization guard

Not all internal permission modes have external equivalents. The toExternalPermissionMode call collapses internal-only names like 'bubble' and 'ungated-auto' to 'default' before sending to CCR. Without this, the remote dashboard would receive meaningless mode names and potentially cycle on internal transitions (default → bubble → default) that are invisible from the outside.

export function externalMetadataToAppState(
  metadata: SessionExternalMetadata
): (prev: AppState) => AppState {
  return prev => ({
    ...prev,
    ...(typeof metadata.permission_mode === 'string'
      ? { toolPermissionContext: {
            ...prev.toolPermissionContext,
            mode: permissionModeFromString(metadata.permission_mode),
          }}
      : {}),
    ...(typeof metadata.is_ultraplan_mode === 'boolean'
      ? { isUltraplanMode: metadata.is_ultraplan_mode }
      : {}),
  })
}

state/AppState.tsx is the React face of the store. It exports three hooks and one provider. The file is compiled React (with _c from the React Compiler), so the raw source reads a little odd — but the semantics are clean.

// Read a slice — re-renders only when the selected value changes
const verbose = useAppState(s => s.verbose)
const model   = useAppState(s => s.mainLoopModel)

// Write without subscribing — stable reference, never causes re-renders
const setAppState = useSetAppState()
setAppState(prev => ({ ...prev, verbose: true }))

// Get the raw store — for passing to non-React helpers
const store = useAppStateStore()
doSomethingOutsideReact(store.getState, store.setState)

// Good — returns existing reference
const { text, promptId } = useAppState(s => s.promptSuggestion)

// Bad — new object every render
const { text, promptId } = useAppState(s => ({ text: s.promptSuggestion.text, promptId: s.promptSuggestion.promptId }))

AppStateProvider setup

AppStateProvider creates the store exactly once (via useState lazy initializer), wires onChangeAppState into it, then applies a one-time fixup if remote settings were loaded before the component mounted:

const [store] = useState(() =>
  createStore(
    initialState ?? getDefaultAppState(),
    onChangeAppState,        // side-effect hook wired here
  )
)

// One-time remote-settings fixup on mount
useEffect(() => {
  const { toolPermissionContext } = store.getState()
  if (toolPermissionContext.isBypassPermissionsModeAvailable
      && isBypassPermissionsModeDisabled()) {
    store.setState(prev => ({
      ...prev,
      toolPermissionContext: createDisabledBypassPermissionsContext(prev.toolPermissionContext)
    }))
  }
}, [])

selectors.ts — pure derivations

state/selectors.ts contains functions that derive computed values from AppState slices without accessing the store or producing side effects. They accept a Pick<AppState, ...> (not the full state) so callers can test them in isolation.

/**
 * Get the currently viewed teammate task, if any.
 * Takes a Pick — not the full AppState — so tests don't need the whole object.
 */
export function getViewedTeammateTask(
  appState: Pick<AppState, 'viewingAgentTaskId' | 'tasks'>
): InProcessTeammateTaskState | undefined { ... }

/**
 * Discriminated union — tells input routing exactly where to send a message.
 */
export type ActiveAgentForInput =
  | { type: 'leader' }
  | { type: 'viewed';     task: InProcessTeammateTaskState }
  | { type: 'named_agent'; task: LocalAgentTaskState       }

export function getActiveAgentForInput(appState: AppState): ActiveAgentForInput { ... }

teammateViewHelpers.ts — colocated state transitions

More complex state transitions for the teammate-view feature live in state/teammateViewHelpers.ts. These are not React hooks — they take setAppState as an argument, making them testable and usable from any context.

// Enter a teammate's transcript view — retain: true blocks eviction, loads from disk
export function enterTeammateView(
  taskId: string,
  setAppState: (updater: (prev: AppState) => AppState) => void,
): void

// Exit back to leader's view — releases retain, schedules eviction if terminal
export function exitTeammateView(
  setAppState: (updater: (prev: AppState) => AppState) => void,
): void

// Context-sensitive x button: abort if running, dismiss if terminal
export function stopOrDismissAgent(
  taskId: string,
  setAppState: (updater: (prev: AppState) => AppState) => void,
): void

How a state update moves from a component through the system:

Not everything in context/ is React Context in the traditional sense. The directory contains a mix of patterns: