claude-code/learn

Learn Claude Code Architecture

A deep-dive educational guide into the internal architecture of Anthropic's Claude Code CLI — the agentic coding assistant that leaked via a .map file in March 2026.

Internal Codename: Tengu
Runtime: Bun
UI Framework: React + Ink (React for CLI)
Language: TypeScript (strict)
Scale: ~1,900 files, 512,000+ lines of code

---

Why This Guide Exists

Claude Code is one of the most sophisticated agentic AI systems ever built. Its architecture contains lessons in:

• Agentic loop design — How to build a multi-turn, tool-calling AI agent
• Terminal UI at scale — 113 React components running in a terminal
• Permission systems — Layered security for autonomous code execution
• Context management — Keeping conversations within token limits
• Extension architectures — Plugins, skills, hooks, and sub-agents

Whether you're building your own AI agent, contributing to open-source AI tools, or just curious about how the sausage is made — this guide is for you.

---

Guide Structure

Start from the top and work down, or jump to whatever interests you:

#	Guide	What You'll Learn
1	System Overview	Bird's-eye view of every layer — entries, UI, core engine, tools, state
2	The Agentic Loop	How query.ts drives the model → tool → model cycle
3	Tool System	How 42 built-in tools are defined, validated, and executed
4	Permission System	Deny rules, allow rules, hooks, classifier, user prompts
5	Context Management	Snip, micro, auto, reactive compact — the full pipeline
6	State Management	AppState store, immutability, and reactive side effects
7	Extension Model	Skills, plugins, hooks, sub-agents, and swarms
8	API Client	claude.ts — streaming, retries, caching, and model fallback
9	UI Architecture	React Ink, 113 components, and the 896KB REPL
10	Configuration and System Prompt	Settings hierarchy, CLAUDE.md discovery, prompt assembly
11	MCP Deep Dive	Transports, tool wrapping, auth, server lifecycle
12	Data Flow Walkthrough	End-to-end trace of a single user request

---

Key Files Quick Reference

File	Size	Role
src/main.tsx	804KB	CLI entrypoint — Commander.js parser + React/Ink bootstrap
src/screens/REPL.tsx	896KB	Interactive terminal shell — the heart of the UI
src/query.ts	1,730 lines	The agentic loop — model ↔ tool cycling
src/QueryEngine.ts	1,296 lines	Session lifecycle owner — wraps query()
src/Tool.ts	793 lines	Tool interface definition — every tool implements this
src/commands.ts	~25K	Slash command registry
src/state/AppStateStore.ts	570 lines	Immutable store with 50+ fields
src/services/compact/	11 files	The entire compaction pipeline

---

Architecture At A Glance

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'primaryBorderColor': '#4a9eff', 'lineColor': '#4a9eff', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f3460', 'edgeLabelBackground': '#1a1a2e'}}}%%
graph TB
    CLI["CLI Entry<br/>main.tsx — 804KB"]:::entry
    SDK["SDK Entry<br/>Programmatic API"]:::entry
    MCP_S["MCP Server<br/>Expose as MCP"]:::entry

    REPL["REPL.tsx — 896KB<br/>Interactive Terminal Shell"]:::ui
    Comps["113 Components<br/>Messages, Diffs, Dialogs"]:::ui
    Hooks["83 React Hooks<br/>Permissions, Input, IDE"]:::ui

    QE["QueryEngine.ts<br/>Session Lifecycle Owner"]:::core
    QL["query.ts — 1730 lines<br/>Agentic Loop"]:::core
    CL["claude.ts — 3420 lines<br/>Anthropic API Client"]:::core

    TD["Tool Interface<br/>Tool.ts"]:::tool
    BT["42 Built-in Tools"]:::tool
    MT["MCP Tools — dynamic"]:::tool
    TO["Tool Orchestration<br/>Parallel Execution"]:::tool

    Compact["Compaction Pipeline<br/>snip / micro / auto /<br/>reactive / collapse"]:::ctx

    Rules["Allow + Deny Rules"]:::perm
    HK["PreToolUse Hooks"]:::perm
    Classifier["Auto-mode Classifier"]:::perm

    AS["AppState Store<br/>Immutable — 50+ fields"]:::state
    SS["Session Storage<br/>Transcripts + Resume"]:::state
    Cfg["Config Layer<br/>Global / Project / CLAUDE.md"]:::state

    Skills["Skills"]:::ext
    Plugins["Plugins"]:::ext
    Agents["Sub-agents + Swarms"]:::ext

    API["Anthropic Messages API"]:::external
    MCP_Ext["External MCP Servers"]:::external
    GrowthBook["GrowthBook + Statsig"]:::external

    CLI --> REPL
    SDK --> QE
    MCP_S --> QE

    REPL --> Comps
    REPL --> Hooks
    REPL --> QE
    REPL --> AS

    QE --> QL
    QL --> CL
    QL --> Compact
    QL --> TO

    CL --> API
    CL --> GrowthBook

    TO --> TD
    TD --> BT
    TD --> MT
    BT --> Rules
    BT --> HK
    MT --> Rules

    Rules --> Classifier

    QE --> SS
    REPL --> Cfg

    Skills --> TD
    Plugins --> TD
    Plugins --> MCP_Ext
    Agents --> QL
    MCP_Ext --> MT

    classDef entry fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef ui fill:#1a1a4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef core fill:#2d1b4e,stroke:#e83e8c,color:#e0e0e0,stroke-width:2px
    classDef tool fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef ctx fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef perm fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef state fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef ext fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef external fill:#333,stroke:#888,color:#aaa,stroke-width:1px,stroke-dasharray: 5 5

---

Prerequisites

To get the most out of these guides, you should be comfortable with:

• TypeScript — The entire codebase is strict TypeScript
• React — The UI uses React (via Ink for the terminal)
• Async generators — The agentic loop and streaming are built on async function*
• LLM APIs — Familiarity with the Anthropic Messages API helps

---