Reading Guide

This guide helps you get the most value from the Claude Code Inspect analysis. Whether you have 2 hours or 20, there’s a reading path for you.

Prerequisites

Before diving in, you should be comfortable with:

Required

• TypeScript — The entire codebase is TypeScript. You need to read generics, discriminated unions, and conditional types fluently.
• Async patterns — async/await, Promise, and especially AsyncGenerator (used throughout for streaming).
• Node.js / Bun basics — Process lifecycle, process.env, signal handling, child processes.

Helpful

• React — The TUI uses React/Ink. Component model knowledge helps for UI sections.
• LLM API concepts — Tokens, streaming, tool use, system prompts, content blocks.
• CLI patterns — Commander.js, ANSI escape codes, terminal I/O.
• Zod — Runtime schema validation used for tool inputs and configuration.

Optional (for specialist paths)

• MCP (Model Context Protocol) — For the MCP integration chapter.
• OpenTelemetry — For the observability/telemetry sections.
• Git internals — For understanding worktree and attribution features.

Three Reading Paths

🚀 Quick Path (2 hours)

For developers who want a working mental model of Claude Code’s architecture:

graph LR
    A["What is Claude Code?<br/>(15 min)"] --> B["Architecture Map<br/>(20 min)"]
    B --> C["Entry & Bootstrap<br/>(20 min)"]
    C --> D["Agentic Loop<br/>(20 min)"]
    D --> E["Tool System Overview<br/>(20 min)"]
    E --> F["Permission & Security<br/>(15 min)"]

What you’ll get: Understanding of the layered architecture, how a user message flows from CLI to API and back, and how tools work.

Chapters to read:

1. Overview → What is Claude Code?
2. Overview → Architecture Map
3. Foundations → Entry & Bootstrap
4. Agentic Loop → Core Loop (when available)
5. Tool System → Overview (when available)
6. Permission & Security → Overview (when available)

📚 Full Path (8 hours)

For developers who want thorough understanding of every major subsystem:

Day 1 (4 hours) — Core Architecture:

1. All four Overview chapters (1 hour)
2. All four Foundations chapters (1.5 hours)
3. Agentic Loop chapters (1.5 hours)

Day 2 (4 hours) — Subsystems: 4. Tool System chapters (1.5 hours) 5. Agent System chapters (1 hour) 6. Permission & Security chapters (1 hour) 7. Context Engine chapters (30 min)

🔬 Specialist Paths

Pick the path that matches your interest:

Path A: “I want to build a tool”

1. Architecture Map — Understand where tools fit
2. Foundations → Streaming Infrastructure
3. Tool System → Tool Interface (when available)
4. Tool System → Built-in Tools Deep Dive (when available)
5. Permission & Security → Tool Permissions (when available)

Path B: “I want to understand the agent system”

1. Architecture Map — Understand the agentic loop
2. Agentic Loop → Core Loop (when available)
3. Agent System → Multi-Agent Architecture (when available)
4. Agent System → Sub-Agent Orchestration (when available)

Path C: “I want to understand the security model”

1. What is Claude Code? — Permission system overview
2. Foundations → Configuration System
3. Permission & Security chapters (all)
4. Tool System → Permission Checking (when available)

Path D: “I want to understand the API layer”

1. Foundations → Streaming Infrastructure
2. Foundations → Error Handling
3. Agentic Loop → API Streaming (when available)
4. Context Engine → Compaction (when available)

Chapter Dependency Map

graph TB
    subgraph "Part 0: Overview"
        O1["What is Claude Code?"]
        O2["Architecture Map"]
        O3["Codebase Stats"]
        O4["Reading Guide"]
    end

    subgraph "Part 1: Foundations"
        F1["Entry & Bootstrap"]
        F2["Configuration System"]
        F3["Streaming Infrastructure"]
        F4["Error Handling"]
    end

    subgraph "Part 2: Agentic Loop"
        A1["Core Loop"]
        A2["API Streaming"]
        A3["Context Management"]
    end

    subgraph "Part 3: Tool System"
        T1["Tool Interface"]
        T2["Built-in Tools"]
        T3["MCP Integration"]
    end

    subgraph "Part 4: Agent System"
        AG1["Multi-Agent Architecture"]
        AG2["Sub-Agent Orchestration"]
    end

    subgraph "Part 5: Permission & Security"
        P1["Permission Engine"]
        P2["Security Model"]
    end

    subgraph "Part 6: Context Engine"
        C1["Compaction"]
        C2["CLAUDE.md System"]
    end

    O1 --> O2
    O2 --> F1
    O2 --> F3
    F1 --> F2
    F3 --> F4
    F1 --> A1
    F3 --> A2
    F4 --> A2
    A1 --> T1
    A2 --> A3
    T1 --> T2
    T1 --> T3
    T1 --> AG1
    AG1 --> AG2
    T1 --> P1
    P1 --> P2
    A3 --> C1
    F2 --> C2

Key insight: The Overview and Foundations chapters are prerequisites for everything else. The specialist chapters (Parts 3-6) can be read in any order after the core.

Recommended Reading Order

For maximum comprehension, we recommend this specific order:

#	Chapter	Time	Key Concept
1	What is Claude Code?	15 min	Product positioning and tech stack
2	Architecture Map	20 min	Layered architecture, data flow
3	Codebase Stats	10 min	Scale and complexity distribution
4	Reading Guide	5 min	(You are here)
5	Entry & Bootstrap	20 min	Process lifecycle, cli.tsx → init.ts → main.tsx
6	Configuration System	15 min	Settings sources, CLAUDE.md hierarchy
7	Streaming Infrastructure	20 min	AsyncGenerator patterns, content blocks
8	Error Handling	15 min	Retry logic, error classification

How to Get the Most Value

1. Read the Source Alongside the Analysis

Every chapter references specific files with paths like src/services/api/withRetry.ts. Open these files as you read — the analysis provides the map, but the source code is the territory.

2. Follow the Data Flow

The most productive way to understand Claude Code is to trace a message from input to output:

User types "fix the bug in auth.ts"
  → main.tsx captures input
    → QueryEngine.submitMessage()
      → processUserInput()
        → query()
          → claude.ts creates API request
            → withRetry handles errors
              → API returns tool_use blocks
                → StreamingToolExecutor runs tools
                  → FileReadTool reads auth.ts
                  → FileEditTool patches auth.ts
                    → Results feed back into next turn

3. Focus on Interfaces, Not Implementations

The Tool interface in src/Tool.ts is more important than any individual tool implementation. The QueryEngine interface matters more than the details of query.ts. Abstractions are stable; implementations change.

4. Notice the Patterns

Several patterns recur throughout the codebase:

• AsyncGenerator for streaming: async function* withRetry(), async *submitMessage()
• Memoized loading: memoize(async (cwd) => ...) for expensive initialization
• Feature flags for DCE: feature('NAME') ? require(...) : null
• Fail-closed defaults: isConcurrencySafe: false, isReadOnly: false
• Source-ordered settings: Later sources override earlier ones

5. Use the Mermaid Diagrams

Every chapter includes Mermaid diagrams for architecture and data flow. These are designed to be the fastest way to build mental models. Read the diagram first, then the text.

Navigation Tips

• Breadcrumbs: Each chapter indicates which part it belongs to
• Cross-references: Chapters link to related content in other parts
• Code blocks: All code examples reference actual file paths — use them to jump into the source
• Key Takeaways: Every chapter ends with a summary box highlighting the most important points

Key Takeaways

Reading Strategy

• 2 hours: Quick Path gives you the mental model — Overview + key Foundations + Agentic Loop
• 8 hours: Full Path covers every subsystem systematically
• Specialist: Pick Path A (tools), B (agents), C (security), or D (API) for targeted learning
• Always start with Overview — the Architecture Map is the single most important chapter
• Read source alongside analysis — this is a map, not a replacement for the territory