Claude Code Architecture: Five Principles for Building Agent Runtimes

Claude Code is not best understood as a CLI that happens to call a model and a few tools.

It is better understood as a local-first runtime host for agentic work. That framing explains the codebase much more cleanly — and once you see it, the surrounding design choices stop looking like overengineering.

The six-layer architecture

What the full source tree looks like

src/
├── cli.tsx
├── main.tsx
├── query.ts
├── Tool.ts
├── tools.ts
├── Task.ts
├── tasks.ts
├── setup.ts
├── replLauncher.tsx
├── coordinator/
│   └── coordinatorMode.ts
├── entrypoints/
│   └── init.ts
├── hooks/
│   ├── useCanUseTool.tsx
│   └── toolPermission/
│       └── handlers/
│           ├── autoHandler.ts
│           ├── interactiveHandler.ts
├── ink/
│   └── ink.tsx
├── query/
│   ├── config.ts
│   ├── tokenBudget.ts
│   └── stopHooks.ts
├── screens/
│   └── REPL.tsx
├── services/
│   ├── analytics/
│   │   ├── index.ts
│   ├── autoDream/
│   │   └── autoDream.ts
│   ├── compact/
│   │   ├── autoCompact.ts
│   │   ├── microCompact.ts
│   │   └── contextCollapse.ts
│   ├── extractMemories/
│   │   └── extractMemories.ts
│   ├── lsp/
│   │   ├── LSPServerInstance.ts
│   │   ├── LSPDiagnosticRegistry.ts
│   ├── mcp/
│   │   ├── config.ts
│   │   ├── client.ts
│   │   ├── ChromeMcpClient.ts
│   ├── relevantMemories/
│   │   └── relevantMemories.ts
│   ├── SessionMemory/
│   │   └── SessionMemory.ts
│   └── tools/
│       ├── toolOrchestration.ts
│       ├── toolExecution.ts
│       ├── StreamingToolExecutor.ts
├── state/
│   ├── AppStateStore.ts
│   └── Store.ts
├── tasks/
│   ├── DreamTask/
│   │   └── DreamTask.ts
│   └── RemoteAgentTask/
│       └── RemoteAgentTask.tsx
├── tools/
│   ├── AgentTool/
│   │   ├── AgentTool.tsx
│   │   └── runAgent.ts
│   ├── BashTool/
│   │   ├── BashTool.tsx
│   │   ├── bashPermissions.ts
│   │   ├── readOnlyValidation.ts
│   ├── FileEditTool/
│   │   └── FileEditTool.ts
│   ├── FileReadTool/
│   │   └── FileReadTool.ts
└── utils/
    ├── memdir.ts
    ├── permissions/
    │   ├── permissions.ts
    │   └── permissionSetup.ts
    ├── processUserInput/
    │   └── processUserInput.ts
    ├── speculation/
    │   ├── speculativeExecute.ts
    ├── swarm/
    │   ├── backends/
    │   │   ├── TmuxBackend.ts
    │   │   ├── ITermBackend.ts
    │   │   └── InProcessBackend.ts
    └── telemetry/
        ├── otel.ts
        ├── betaSessionTracing.ts

Five principles distilled from the source

1. Capability assembly matters as much as model execution

Claude Code spends substantial architecture budget on deciding what capabilities exist in this session, which are visible, which are trusted, and which are allowed right now.

That is why tools.ts, commands.ts, utils/permissions/, and services/mcp/ all feel central rather than peripheral. The product is assembling a governed runtime surface, not exposing raw functions.

2. The turn loop is the real execution unit

The right execution unit is not a single API request — it is a recoverable turn loop with named continuation reasons.

The seven recovery conditions in query.ts cover the full failure surface: fallback model retry, compaction circuit breaker, max output tokens recovery, prompt-too-long reactive compact, stop hook resume, tool use continuation, and post-compact continuation. Each is named as a transition value so tests can assert which path fired without inspecting message content.

The five-step message preprocessing pipeline runs before every API call in a load-bearing order: budget → snip → microcompact → context collapse → autocompact. The ordering is not arbitrary — each step can short-circuit the next.

3. Tool execution is an internal subsystem

Tools are not callbacks hanging off the side of the loop. The tool execution subsystem has scheduling (partitionToolCalls — concurrent vs serial per invocation), governance (permission pipeline with pre/post hooks), and streaming-aware behavior (StreamingToolExecutor starts tools as inputs complete, not after the full response arrives).

BashTool's five defense layers illustrate the design philosophy: tree-sitter AST parsing (fail-closed on unparseable input), read-only validation, path validation, destructive command warnings, and sandbox routing. The speculative pre-check pattern — validating bash permissions before showing the approval dialog — is the kind of UX detail that only emerges from thinking about the full flow.

4. State is a control plane, not just UI bookkeeping

AppStateStore (~80 fields, DeepImmutable<T>) tracks tasks, permissions, MCP clients, overlays, notifications, and other runtime objects that outlive any single render. The Store itself is 35 lines. The key design: useSyncExternalStore selectors prevent unnecessary re-renders, and the optional onChange callback centralizes side effects.

The ToolUseContext isolation model is worth noting: sub-agents get a no-op setAppState (so they cannot mutate parent session state), but setAppStateForTasks always pierces to the root Store. Fork agents use byte-exact prompt threading to preserve prompt cache coherence with the parent.

5. Detached work becomes first-class runtime

Background shell tasks, local subagents, in-process teammates, and remote sessions all become managed runtime objects with lifecycle, observation, stop semantics, and persistence — not hidden implementation details.

The DreamTask pattern is reusable: promote any long-running background operation into a Task, make it observable in the UI, add cancellation. This is why AutoDream appears as a named task rather than silent background work.

Non-obvious details that change the mental model

Side-effect hoisting at startup. startMdmRawRead() and startKeychainPrefetch() fire at T+2ms between import statements — before module evaluation completes at T+137ms. The API preconnection HEAD request at T+150ms puts a TCP+TLS connection into Bun's keep-alive pool before any model call is needed. These are startup latency optimizations buried in the import order.

SYSTEM_PROMPT_DYNAMIC_BOUNDARY. A sentinel string that splits the system prompt into a static section (gets a global cache entry) and a dynamic section (null cache header, never cached). Changing anything below the boundary does not invalidate the cached static prefix. This is load-bearing for prompt caching cost.

Chrome MCP runs in-process. Instead of spawning a ~325MB subprocess for Chrome integration, Claude Code runs the Chrome MCP client in-process. The implementation is behind ChromeMcpClient.ts and the initialization is gated to avoid paying the cost when Chrome MCP is not configured.

DA1 terminal capability detection. Rather than writing a test string and reading the response (which requires a timeout), Claude Code uses the DA1 (Device Attributes) ANSI escape sequence to probe terminal capabilities synchronously. This is how it detects 256-color and true-color support without a TTY timeout.

The memory system's fifth layer. Most descriptions stop at four memory layers. The fifth — Relevant Memories — fires a lightweight Sonnet side-query before each turn to select at most 5 contextually appropriate memory files from memdir. This is what makes large memdirs scale: you pay only for what is relevant to the current turn.

The main design lesson

Serious agent products are built around runtime architecture, not just reasoning quality.

The model matters, but the harder product questions are:

• what gets assembled into the session
• what actions are governed
• what state persists
• how failure recovers
• how detached work is controlled

Claude Code is worth studying because the source keeps answering those questions in concrete runtime terms rather than deferring them to "the model will figure it out."