claude-code-architecture-overview

# 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

Lessons

References