CodeWisdom

Claude Code: Source Reading Series — Start Here

•4 min read•AI Agents

The entry point for the Claude Code source-reading series. Five layers, sixteen posts. Start here to navigate the series in order.

ai-agentsclaude-codearchitectureseries-indexruntime

This series works through the learning-claude-code source top to bottom.

Each post covers one subsystem. Together they build a complete picture of how a serious agent product is actually constructed — not at the level of prompts, but at the level of runtime architecture.

If you read them in order, by the end you will have a mental model that explains every major design decision in Claude Code.

Start at Layer 1. Follow the arrows.

Layer 1 — The Runtime Host

Before any agent loop runs, Claude Code boots a runtime host. This layer explains what that means.

| # | Post | What you will learn | |---|------|---------------------| | 01 | Boot & Session Assembly | How main.tsx normalizes launch modes, assembles permissions, and composes a session before the first turn | | 02 | Input Pipeline | How processUserInput routes text / !bash / /slash into three separate paths; how speculative execution and prompt suggestions work as latency infrastructure |

After Layer 1 you understand: the product boots a governed session, not a bare API wrapper.

Layer 2 — The Core Loop

The agent loop is not a while(true). This layer explains the real execution unit.

| # | Post | What you will learn | |---|------|---------------------| | 03 | Query Loop | How query.ts manages streaming, compaction, tool-use continuation, fallback, and stop conditions as a single recoverable AsyncGenerator | | 04 | Command System | How six source types assemble into a memoized command registry; the difference between REMOTE_SAFE and BRIDGE_SAFE commands |

After Layer 2 you understand: the turn loop is the real execution unit, and it has four distinct recovery paths.

Layer 3 — The Capability Surface

What the agent can do is not a list of functions. It is a governed surface assembled per session.

| # | Post | What you will learn | |---|------|---------------------| | 05 | Tool Protocol & Registry | The 20+ property Tool interface; buildTool() fail-closed defaults; how the registry is assembled per session | | 06 | Tool Execution Service | How partitionToolCalls schedules batches; StreamingToolExecutor; speculative execution; tombstone cleanup | | 07 | Permission Engine & Sandbox | The 7-step decision tree; bypass-immune safety gates at steps 1e–1g; how the Sandbox system wraps @anthropic-ai/sandbox-runtime | | 08 | MCP Assembly | Seven config sources; getMcpServerSignature() content-based dedup; how MCP tools, commands, and resources expand into three surfaces | | 09 | LSP Integration | Persistent multi-server LSP stack; LSPDiagnosticRegistry (10/file, 30 total, LRU); push-based passive diagnostic collection |

After Layer 3 you understand: capability assembly is a first-class architectural concern, not a list of callbacks.

Layer 4 — The Agent Services

What makes Claude Code behave like a runtime product rather than a stateless API client.

| # | Post | What you will learn | |---|------|---------------------| | 10 | Memory System | Four layers: memdir injection → SessionMemory compaction → ExtractMemories taxonomy → AutoDream consolidation; 5-gate AutoDream; mtime-based distributed lock | | 11 | Task Runtime | Five task types; LocalMainSessionTask; how background shell tasks become first-class runtime objects | | 12 | Subagent Runtime | How runAgent materializes a subagent turn; setAppState vs setAppStateForTasks; lifecycle and cancellation | | 13 | Swarm & Multi-Agent | coordinatorMode synthesize-first strategy; three swarm backends (TmuxBackend binary tree / ITermBackend / InProcessBackend); disjoint file ownership |

After Layer 4 you understand: memory, tasks, and multi-agent coordination are first-class services, not add-ons.

Layer 5 — The Platform

The platform layer that makes the whole system observable and operable.

| # | Post | What you will learn | |---|------|---------------------| | 14 | UI Runtime | AppStateStore (75+ fields, 9 React contexts); external store with useSyncExternalStore selectors; custom Ink frame pipeline | | 15 | Analytics & Observability | Dual-sink event emission; never-type PII enforcement; OTEL spans wrapping the full turn; betaSessionTracing system-reminder extraction; Perfetto/Chrome Trace export | | 17 | REPL Runtime | REPL.tsx (5005 lines, 30+ hooks); QueryGuard sync state machine; stale-read discipline via store.getState(); overlay priority stack; useDeferredValue for input responsiveness |

After Layer 5 you understand: the UI is a projection of a session control plane, and observability is instrumented at every layer.

Synthesis

| # | Post | What you will learn | |---|------|---------------------| | 16 | Architecture Review | The five cross-cutting principles that unify all posts; the one design lesson that applies to any agent product | | 18 | Tool Implementations | BashTool 4-layer security pipeline, speculative pre-checks, auto-backgrounding; FileReadTool device blocking; AgentTool nesting depth limit; autoCompact circuit breaker |

Three reading paths

Choose your reading path

You do not have to read all 16 posts. Pick the path that matches your goal.

  1. 1

    Quick overview (3 posts)

    Posts 01, 03, 16

    Boot (01) → Query Loop (03) → Architecture Review (16). You get the runtime framing, the core execution unit, and the synthesis. About 30 minutes.

  2. 2

    The execution engine (6 posts)

    Posts 01–03, 05–07

    Boot (01) → Input Pipeline (02) → Query Loop (03) → Tool Protocol (05) → Tool Execution (06) → Permission Engine (07). Everything from input to tool result. About 90 minutes.

  3. 3

    Full series in order (18 posts)

    Posts 01–18

    All five layers in sequence. Each post builds on the last. Start at Layer 1 and follow the arrows. Recommended if you are building an agent product and want to understand every design decision.

Source file coverage

Every post in this series is anchored to real source files from learning-claude-code. The series now covers over 40 source files across all major subsystems.

The Boot post's source map has the full inventory with status badges (Deep Read / In Progress / Indexed / Deferred) and cross-links to every post.

What this series is not

It is not a tutorial on how to use Claude Code.

It is a source-reading series for engineers who want to understand how a production-grade agent runtime is built — what architectural decisions were made, why they were made, and what problems they solve.

The goal is to give you a mental model you can apply when building your own agent systems.