Full Architecture Overview

Over the previous 49 lessons we explored every subsystem in isolation: the boot sequence, query engine, tool system, skills, agents, permissions, MCP, state management, and more. This capstone lesson stitches them all together. By the end you will have a single mental model that explains exactly what happens — at the code level — from the moment you press Enter on a prompt to the moment the response finishes rendering.

Claude Code is a TypeScript application built on Bun, React/Ink (terminal UI), and the Anthropic API. Its architecture has six clearly-separated layers that hand off responsibility in sequence:

This ASCII diagram maps every major component and its relationship to the others. Read it top-down: the user's keystroke flows downward through each layer until it reaches the API, then the response bubbles back up through tools and the UI.

Now let's trace a single user message — say "refactor this function" — through the entire stack. Every numbered step maps to real code in the source tree.

The boot sequence is carefully orchestrated to minimize time-to-first-render. Three categories of work run in parallel as early as possible:

QueryEngine (introduced in a later refactor) extracts what was the monolithic ask() function into a class that owns the full conversation lifecycle. One instance lives per conversation session.

State the engine owns

class QueryEngine {
  private config: QueryEngineConfig       // tools, commands, mcpClients, model, ...
  private mutableMessages: Message[]       // full conversation history (grows each turn)
  private abortController: AbortController  // shared with all tools in this session
  private permissionDenials: SDKPermissionDenial[]  // accumulated for SDK result
  private totalUsage: NonNullableUsage     // token counts across all turns
  private readFileState: FileStateCache   // snapshot of files read this session
  private discoveredSkillNames: Set<string> // skills seen in this turn (for telemetry)
  private loadedNestedMemoryPaths: Set<string> // CLAUDE.md files already injected
}

submitMessage() — the turn lifecycle

Each call to submitMessage() is an async generator yielding SDKMessage events. The sequence every turn:

The query() loop — iteration anatomy

// query.ts — simplified loop skeleton
async function* queryLoop(params) {
  let state = { messages, turnCount: 1, autoCompactTracking, ... }
  const config = buildQueryConfig()   // snapshot env/statsig state

  while (true) {
    // 1. Optionally start skill/job prefetch (async, consumes settled results only)
    // 2. Send streaming API request via deps.sendRequest()
    for await (const event of streamEvents) {
      yield event  // passes text deltas directly to REPL
      if (event.type === 'tool_use') collectToolUse(event)
    }

    // 3. Check stop reason
    if (stopReason === 'end_turn') return 'success'

    // 4. Execute tools (StreamingToolExecutor — parallel where possible)
    for await (const result of runTools(toolUseBlocks, canUseTool, context)) {
      yield result
    }

    // 5. Token budget / compact checks → may compact and continue
    // 6. Append tool_results to messages, increment turnCount, loop
  }
}

Every capability Claude can invoke is a Tool. The tool system is intentionally flat — there is no tool hierarchy, just a registry function getAllBaseTools() in tools.ts that returns the authoritative list.

Tool interface (Tool.ts)

// Simplified Tool interface
interface Tool {
  name: string                                         // must be stable (used in Statsig cache key)
  description: string                                  // injected into system prompt
  inputSchema: ZodSchema                             // validation before call()
  isEnabled(): boolean                               // feature-gate / env check
  call(input, context: ToolUseContext):               // async generator
    AsyncGenerator<ToolProgressData, ToolResult>
  renderToolResult(result, context): React.ReactNode  // Ink UI rendering
}

ToolUseContext — the tool's window into the world

Every tool call receives a ToolUseContext that bundles together everything the tool might need without coupling it to global state:

Feature-gated tools

Many tools are conditionally included based on feature() flags (Bun bundle-time dead code elimination) or environment variables. This keeps the tool list deterministic for Anthropic's prompt cache key:

// tools.ts — feature gate pattern
const SleepTool =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null

// getAllBaseTools() filters nulls from the array
// NOTE: this list is synced to Statsig console for prompt cache invalidation

Claude Code has a two-layer state model. Understanding which layer to use for what is essential to understanding the codebase.

The key design principle: bootstrap/state.ts is a module-level singleton (plain JS object) while AppState is React context. This separation means the query engine and tools can access session identity without importing React, while the UI can re-render reactively on any AppState change.

// bootstrap/state.ts — the singleton shape (partial)
type State = {
  originalCwd: string
  projectRoot: string
  totalCostUSD: number
  totalAPIDuration: number
  cwd: string
  modelUsage: { [modelName: string]: ModelUsage }
  mainLoopModelOverride: ModelSetting | undefined
  isInteractive: boolean
  sessionId: SessionId
  sdkBetas: BetaMessageStreamParams['betas']
  hookRegistry: RegisteredHookMatcher[]
  meter: Meter | undefined
  tokenBudgetInfo: { remainingTokens: number; ... }
  // ... ~40 more fields, all process-lifetime
}

// state/AppStateStore.ts — the React state shape (partial)
type AppState = DeepImmutable<{
  settings: SettingsJson
  mainLoopModel: ModelSetting
  toolPermissionContext: ToolPermissionContext
  messages: Message[]
  mcpClients: MCPServerConnection[]
  agentDefinitions: AgentDefinitionsResult
  speculation: SpeculationState
  fileHistory: FileHistoryState
  plugins: LoadedPlugin[]
  tasks: TaskState | null
  // ... ~50 more fields
}>

A "session" in Claude Code is a persistent conversation with a unique UUID. Sessions are stored as JSONL transcript files under ~/.claude/projects/<cwd-hash>/<session-id>.jsonl.

Session lifecycle

// Startup: generate or restore session ID
getSessionId()          // reads bootstrap/state.ts
registerSession()        // registers in concurrent sessions tracking
countConcurrentSessions() // used for display in status bar

// During conversation:
recordTranscript(messages)   // enqueues write (lazy 100ms JSONL flush)
flushSessionStorage()         // forced flush (EAGER_FLUSH env / cowork)
cacheSessionTitle()           // first user message → title for resume UI

// Resume path (--continue / --resume):
loadTranscriptFromFile()      // reads JSONL back into Message[]
processResumedConversation()  // validates + replays into initial messages

MCP (Model Context Protocol) servers connect as MCPServerConnection objects held inside AppState.mcpClients. They are initialized before the first query and passed into every ToolUseContext.

MCP tools are not in getAllBaseTools() — they are dynamically added alongside the base tools at session startup via getMcpToolsCommandsAndResources(). This is why MCP tool names can conflict with base tool names: the deduplication happens at load time.

Every tool call passes through canUseTool() before execution. This single function is the architectural choke point for all permission decisions.

// The permission gate — called by query.ts before runTools()
const wrappedCanUseTool: CanUseToolFn = async (
  tool, input, toolUseContext, assistantMessage, toolUseID, forceDecision
) => {
  const result = await canUseTool(tool, input, toolUseContext, ...)
  if (result.behavior !== 'allow') {
    // Track for SDK result reporting
    this.permissionDenials.push({ tool_name, tool_use_id, tool_input })
  }
  return result
}

When the conversation grows large enough to threaten the model's context window, Claude Code triggers automatic compaction. This is transparent to the user.

Hooks let users inject shell commands or callbacks at specific lifecycle points. They are configured in settings.json and captured once at startup (immutable snapshot pattern).

The codebase has two distinct runtime paths that share QueryEngine but differ significantly in their UI and startup behavior:

The AgentTool enables recursive execution: Claude can spawn sub-agents, each with their own QueryEngine instance and a restricted tool set.

In swarm mode (ENABLE_AGENT_SWARMS=true), agents communicate via the Unix Domain Socket (UDS) messaging server started in setup.ts. Each agent registers with TeamCreateTool and can send messages back to the coordinator via SendMessageTool.

Everything together — the complete timeline from cold start to streaming response:

1. Async generator threading

The entire data flow from API to UI is a chain of async generators. query() yields StreamEvents, QueryEngine.submitMessage() yields SDKMessages, and the REPL consumes them. This enables true streaming without callbacks or event buses.

2. Dead code elimination via feature()

Bun's bundle-time feature('FLAG_NAME') completely removes disabled feature branches from the compiled binary. This means the tool list is deterministic per build (important for Anthropic's prompt cache key), and disabled features add zero runtime overhead.

3. Cache-warming for latency

Critical paths (system prompt, tools, commands, model capabilities) are all pre-warmed in parallel during setup/startup. By the time the user submits their first prompt, nearly all expensive I/O has already completed. The pattern: fire async work, discard the promise, and memo/cache the result.

4. Immutable AppState + mutable bootstrap/state

React state is immutable (DeepImmutable) to prevent accidental mutation and enable React's change detection. But session-level constants (cwd, sessionId, model) live in a plain module singleton that is intentionally not React state — these values are accessed by non-React code deep inside the query engine.

5. The isBareMode() fast path

Every expensive startup operation is guarded by if (!isBareMode()). This single flag (true when running headless) skips React, Ink, UDS messaging, plugin prefetch, deferred prefetches, and all interactive-only setup. Headless execution becomes nearly pure compute.

6. Parallel subprocess investment

Instead of sequential I/O, the codebase fires subprocesses and async operations as early as possible and lets them run in parallel with JavaScript execution. startMdmRawRead() and startKeychainPrefetch() both fire before the 135ms module graph finishes evaluating. By the time the code that consumes their results runs, they're usually already done.