Claude Code Architecture Overview

• Episode ID: epi-20260409-913321ff7c92
• Scope: shared
• Created: 2026-04-09T20:22:41Z

Question

What is the overall architecture of Claude Code and how do its major systems relate?

Summary

Claude Code is a 512K+ line TypeScript platform runtime built on Bun with a React/Ink terminal UI. The architecture separates into 5 layers: Entrypoints (CLI/Desktop/Web/SDK/IDE), Runtime (REPL/Query/Hooks/State), Engine (QueryEngine/Context/Model/Compact), Tools (100+ tools/MCP/Skills/Agents), Infrastructure (Auth/Storage/Cache/Analytics/Bridge). The core is query.ts, a 1,729-line async generator while(true) loop with 6 stages per turn and 9 typed exit paths. StreamingToolExecutor enables parallel read-only tool execution during API streaming. The 5-tier compaction pipeline manages context budget. QueryEngine.ts (1,295 lines) supervises sessions above the loop. Every design decision bends toward prompt cache preservation.

Findings

• The async generator pattern unifies streaming, interruption, budget control, and tool recursion in a single function
• The 5-tier compaction pipeline represents different Pareto-optimal tradeoffs between cost and information loss
• Production implementation adds ~12 engineering layers over a conceptual 30-line core loop
• The Bridge system abstracts transport so the same engine powers all interfaces

Lessons

• Cache is load-bearing infrastructure, not an optimization — breaking it multiplies costs 5-10x
• The model is the planner — no external DAG or classifier routes requests

References

none