Home › Entities › Five-Layer Architecture

Five-Layer Architecture

claude-code is not a thin API wrapper. The most structurally important finding from redreamality.com's analysis of all 1,884 files was a clean five-layer separation — a platform runtime that happens to ship with a terminal interface.

The Five Layers

Layer Contents
1 — Entrypoints CLI / Desktop / Web / SDK / IDE Extensions
2 — Runtime REPL loop / Query executor / hooks-system / State manager
3 — Engine queryengine-ts / Context coordinator / Model manager / compaction-pipeline
4 — Tools & Capabilities 100+ tools / plugin-system / MCP / skill-system / Agent / Command
5 — Infrastructure Auth / Storage / cache-economics / Analytics / bridge-system transport

The bridge-system layer abstracts transport, so the same QueryEngine powers the desktop app, web client, IDE extensions, and programmatic SDK. The same conversation object runs regardless of interface.

Six-Phase Startup Sequence

Fast-path routing → Initialization → Telemetry → Setup → Command loading → REPL launch

Startup parallelizes MDM policy reads, keychain credential prefetch, and API preconnect using side-effects before heavy module evaluation. The --bare flag skips hooks, UI, and automatic file system discovery — reducing cold-start by 10x for batch/CI/serverless contexts.

Scale

Metric Count
Source files ~1,900
Lines of code 512,000+
Utility files ~330
Tool implementations ~40
Slash commands ~85+
React terminal UI components 146
React hooks 85+
Feature flags 108 (not the widely cited 44)

Tech Stack

Category Technology
Runtime Bun
Language TypeScript (strict)
Terminal UI React 18 + Ink with custom reconciler on Yoga WASM
CLI parsing Commander.js
Schema validation Zod v4
Code search ripgrep (via GrepTool)
Protocols MCP SDK, LSP
API Anthropic SDK
Telemetry OpenTelemetry + gRPC (lazy-loaded, ~1.1MB)
Feature flags growthbook
Auth OAuth 2.0 + JWT + macOS Keychain

Design Philosophy

The community described the architecture as "closer to VS Code's extension host or Emacs's Lisp core than to a typical AI wrapper." Production implementation adds approximately 12 engineering layers over the conceptual 30-line core loop — the query-ts async generator.

The eight synthesized design principles: 1. The model is the planner (no external DAG) 2. grep-over-rag always 3. cache-economics as load-bearing infrastructure 4. compaction-pipeline is last resort 5. Tools are first-class Zod schemas 6. Everything observable via BigQuery telemetry 7. Safety is a layer, not a property (permission-pipeline) 8. Dead-code elimination is the deployment mechanism

Key Claims

Sources