05-state-management

Inkdown

Start writing

Shared from "Claude-Code" on Inkdown

State Management

How the application tracks and shares state across its many subsystems.

Two Layers of State

Claude Code uses two distinct state management patterns:

Bootstrap State — Global singleton with getter/setter functions
AppState Store — Redux-like store with React integration

Bootstrap State (`bootstrap/state.ts`)

A singleton module that holds global session state. Think of it as "carefully managed global variables."

Design Principles

Plain text

getOriginalCwd()        — Where the user started
getProjectRoot()        — Stable project root (set once)
getCwdState()           — Current working directory (can change)
getAdditionalDirectoriesForClaudeMd()  — Extra dirs from --add-dir

Plain text

getTotalCostUSD()       — Total API cost in dollars
getTotalAPIDuration()   — Total API wait time
getTotalToolDuration()  — Total tool execution time
getTotalInputTokens()   — Total input tokens
getTotalOutputTokens()  — Total output tokens
getTotalLinesAdded()    — Lines of code added
getTotalLinesRemoved()  — Lines of code removed

Plain text

getInitialMainLoopModel()     — Model set at startup
getMainLoopModelOverride()    — Runtime model override
getModelUsage()               — Per-model token usage
getSdkBetas()                 — SDK beta feature flags

Plain text

getMeter()              — OTel meter for metrics
getTracerProvider()     — OTel tracer provider
getEventLogger()        — OTel event logger
getSessionCounter()     — Session counter metric
getCostCounter()        — Cost counter metric
getTokenCounter()       — Token counter metric

Plain text

getIsInteractive()            — Interactive TUI vs headless
getClientType()               — cli, sdk, github-action, etc.
getKairosActive()             — Assistant mode active
getIsRemoteMode()             — --remote flag
getStrictToolResultPairing()  — Strict tool result mode

Plain text

getFastModeHeaderLatched()     — Once on, stays on
getAfkModeHeaderLatched()      — Once on, stays on
getCacheEditingHeaderLatched() — Once on, stays on
getThinkingClearLatched()      — Once on, stays on

Plain text

addInvokedSkill(skillName)     — Track skill invocations
getInvokedSkills()             — Get all invoked skills
markPostCompaction()           — Flag set after compaction
consumePostCompaction()        — Clear and return flag

Plain text

getLastAPIRequest()           — Last API request body
getLastAPIRequestMessages()   — Messages from last request
getLastClassifierRequests()   — Classifier requests
addToInMemoryErrorLog(error)  — Recent errors (capped at 100)

Plain text

┌─────────────────────────────────────────────────────────┐
│                    AppStateProvider                     │
│                                                         │
│  const store = createStore(initialState, onChange)      │
│                                                         │
│  ┌──────────────┐  ┌───────────────┐                   │
│  │ AppStoreCtx  │  │ onChangeState │                   │
│  │ (React ctx)  │  │ (side effects)│                   │
│  └──────┬───────┘  └───────┬───────┘                   │
│         │                  │                           │
│  ┌──────┴──────┐    ┌──────┴──────┐                    │
│  │useAppState  │    │ Persist to  │                    │
│  │(subscribe)  │    │ disk, notify│                    │
│  └─────────────┘    │ CCR, etc.   │                    │
│                     └─────────────┘                    │
└─────────────────────────────────────────────────────────┘

TypeScript

function createStore<T>(initialState: T, onChange?: (newState: T, oldState: T) => void) {
  let state = initialState
  const listeners = new Set<() => void>()

  return {
    getState: () => state,
    setState: (updater: (prev: T) => T) => {
      const next = updater(state)
      if (!Object.is(next, state)) {
        const old = state
        state = next
        onChange?.(next, old)        // Side effects
        listeners.forEach(l => l())  // Notify subscribers
      }
    },
    subscribe: (listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)
    }
  }
}

TypeScript

replBridgeState: 'disconnected' | 'connecting' | 'connected' | 'failed'
replBridgeSessionUrl: string | null
remoteConnectionStatus: 'disconnected' | 'connecting' | 'connected'
remoteSessionUrl: string | null
remoteBackgroundTaskCount: number

TypeScript

// Subscribe to a slice of state
const model = useAppState(s => s.mainLoopModel)

// Get the setState function
const setState = useSetAppState()

// Get the full store (for non-React code)
const store = useAppStateStore()

// Safe version (works outside provider)
const value = useAppStateMaybeOutsideOfProvider(s => s.field)

TypeScript

// ✅ GOOD — returns existing reference
const { text } = useAppState(s => s.promptSuggestion)

// ❌ BAD — creates new object every render → infinite re-renders
const data = useAppState(s => ({ text: s.promptSuggestion.text }))

State Change	Side Effect
`toolPermissionContext.mode`	Notify CCR (remote daemon), notify SDK listeners
`mainLoopModel` set/cleared	Save to settings, set/clear model override
`expandedView` changed	Persist `showExpandedTodos` and `showSpinnerTree` to disk
`verbose` changed	Persist to global config
`tungstenPanelVisible` changed	Persist to global config (ant-only)
`settings` changed	Clear auth caches, re-apply env variables

TypeScript

// Look up the teammate task being viewed
getViewedTeammateTask({ viewingAgentTaskId, tasks })

// Determine where user input should be routed
getActiveAgentForInput(appState)
// Returns: { type: 'leader' } | { type: 'viewed', task } | { type: 'named_agent', name }

TypeScript

function getDefaultAppState(): AppState {
  return {
    settings: getInitialSettings(),
    mainLoopModel: getDefaultMainLoopModel(),
    thinkingEnabled: shouldEnableThinkingByDefault(),
    promptSuggestionEnabled: shouldEnablePromptSuggestion(),
    tasks: [],
    mcp: { clients: [], tools: [], commands: [], resources: [] },
    plugins: { enabled: new Set(), disabled: new Set(), errors: [], ... },
    replBridgeState: 'disconnected',
    // ... many more defaults
  }
}

Plain text

Settings file changes
    │
    ▼
useSettingsChange(callback)
    │
    ▼
applySettingsChange(appState, newSettings)
    │
    ▼
store.setState(prev => ({
  ...prev,
  settings: newSettings,
  // Derived state updates...
}))
    │
    ▼
onChangeAppState fires
    ├─ Clear auth caches
    ├─ Re-apply environment variables
    └─ Notify external systems

File	Purpose
`src/bootstrap/state.ts`	Global singleton state (session ID, cost, model, etc.)
`src/state/store.ts`	Generic store implementation
`src/state/AppStateStore.ts`	AppState type and default state factory
`src/state/AppState.tsx`	React provider and hooks
`src/state/onChangeAppState.ts`	Side effects on state change
`src/state/selectors.ts`	Computed state selectors
`src/state/teammateViewHelpers.ts`	Teammate view helper functions

05-state-management

State Management

Two Layers of State

Bootstrap State (bootstrap/state.ts)

Design Principles

05-state-management

State Management

Two Layers of State

Bootstrap State (bootstrap/state.ts)

Design Principles

What It Tracks

Session Identity

Directories

Cost & Usage

Model Configuration

Telemetry (OpenTelemetry)

Session Behavior

Prompt Cache Optimization

Skills & Compaction

Debug & Diagnostics

AppState Store (state/)

Architecture

The Store (store.ts)

AppState Shape

Settings & Model

UI State

Tasks & Agents

MCP

Bridge / Remote

Permissions

Companion (Buddy)

Tmux / Tungsten

Web Browser

Computer Use

Notifications

Communication (Swarms)

React Hooks

Side Effects (onChangeAppState.ts)

Selectors (selectors.ts)

Default State Factory

Settings Change Handling

Key Files Reference

Bootstrap State (`bootstrap/state.ts`)

Bootstrap State (`bootstrap/state.ts`)

AppState Store (`state/`)

The Store (`store.ts`)

Side Effects (`onChangeAppState.ts`)

Selectors (`selectors.ts`)