April 3, 2026·6 min read·v2.1.88

Claude Code Architecture

AI coding agent runtime — 512K lines of TypeScript. Query engine, permission-gated tool system, multi-agent orchestrator, bash security parser, memory subsystem, and unreleased autonomous daemon.

coding-agentanthropicmulti-agenttool-systemsecurityautonomous

View repository →

Terminal UI & Rendering

Core Engine & Query

Memory & Storage

Tool System (40+)

Agent Orchestration

Config & Permissions

Security & Parsing

External Services

System Layers

User Interfaces

⌨Terminal TUIInt32Array char pool, bitmask styles, ~50x perf

🖥VS Code ExtensionEmbedded IDE integration

📱Web InterfaceBrowser-based session view

>_CLIclaude --print, --resume, --mcp-config

Query Engine (~46,000 lines)

🧠QueryEngine.tsPrompt construction, streaming, retries

💰Token CounterPer-session cost tracking

📦Prompt CacheSYSTEM_PROMPT_DYNAMIC_BOUNDARY split

🔍Cache Break Detection14 vectors, sticky latches

📊A/B TestingConciseness, output tokens, verbosity

Tool System (40+ tools, ~29,000 lines)

📄Read/Write FilesPermission-gated file access

⌨Bash ExecutionAST-parsed, 22 validators

✏Edit ToolDiff-based file modification

🌐Web FetchHTTP requests with sandboxing

🔧MCP ClientExternal tool servers

💻LSP IntegrationLanguage server protocol

🔎Grep/GlobCodebase search tools

++30 more tools

Agent Orchestration

👑Lead AgentPrimary session coordinator

🤖SubagentsIsolated context, restricted tools

✅Verification AgentAdversarial — distrusts builder

🎯coordinatorMode.tsOrchestration-as-prompt

Security Layer (~9,700 lines)

🛡Bash Parsertree-sitter WASM AST

🔒22 ValidatorsZsh builtins, unicode, IFS injection

⚠Permission GatesModel proposes, tool disposes

🕵Undercover ModeHide system prompt internals

🎭Anti-DistillationFake tools, summary signatures

Memory & Storage

📝MEMORY.mdWorking context — always loaded

📁CLAUDE.mdProject config — per-repo

💭Session HistoryPast conversations — selective search

🌙AutoDreamBackground memory consolidation

📊TelemetrySentry, PostHog, usage metrics

External Services

🧠Anthropic APIClaude models + prompt caching

🔧MCP ServersExternal tool providers

📦npm RegistryDistribution + updates

🔑OAuth ProvidersGitHub, Google auth flows

Core Flow — Query Lifecycle

User input — Terminal TUI captures prompt via Int32Array-backed renderer with bitmask-encoded style metadata

↓

Prompt construction — QueryEngine.ts builds prompt: static system (cached) + DYNAMIC_BOUNDARY + session context (CLAUDE.md, git status, date)

↓

Cache check — promptCacheBreakDetection.ts evaluates 14 vectors. Sticky latches prevent mode toggles from invalidating. DANGEROUS_uncachedSystemPromptSection() annotated

↓

API call — Streaming request to Anthropic API with token counting, cost tracking, retry logic, and anti-distillation flags

↓

Tool calls — Model proposes tool use → permission gate checks → user approval if needed → tool executes in sandbox → result returned to context

↓

Subagent spawn (if needed) — coordinatorMode.ts spawns isolated subagents with restricted tool sets. Verification agent distrusts builder output

↓

Context compaction — When context grows too long, a second smaller Claude summarises it. Chain-of-thought in analysis tags, stripped before injection

Permission Architecture

Tool Permission Model

Model decides what to attempt

Tool system decides what is permitted

Permission checks before execution

User approval flows in tool layer

Not delegated to the LLM

Discrete, independently permissioned

bypassPermissions mode for automation

Bash Security (9,700 lines)

tree-sitter WASM parser builds AST

22 unique security validators

18 blocked Zsh builtins

Zsh equals expansion defence (=curl)

Unicode zero-width space injection

IFS null-byte injection guard

Default posture: ask the human

Known: parser differential (deprecated still load-bearing)

Key Subsystem — KAIROS Autonomous Daemon (Unreleased)

KAIROS/ (autonomous daemon mode)
├── daemon.ts               ← Background workers, unattended execution
├── webhooks.ts             ← GitHub webhook subscriptions
├── cron.ts                 ← 5-minute refresh schedule
├── dream.ts                ← /dream command for memory consolidation
└── memory/
  ├── MEMORY.md           ← Working context (always loaded)
  ├── project-notes/      ← Structured files (on-demand)
  └── session-history/    ← Past conversations (selective search)

AutoDream Consolidation:
├── Triple gate: 24h elapsed + 5 sessions + file lock
├── mtime-as-timestamp (lock file mtime = lastConsolidatedAt)
├── Stale after 1h even if PID alive (guards PID reuse)
└── On failure: mtime rolls back → restores previous state

Memory Architecture

Working Context (MEMORY.md)

Always loaded into system prompt, User preferences / project notes, Updated by AutoDream consolidation

Project Config (CLAUDE.md)

Per-repo instructions, Loaded after DYNAMIC_BOUNDARY (no cache bust), Git status / current date appended

Session History

Past conversation logs, Selective search on demand, Compacted by second Claude when too long

AutoDream Consolidation

Fires when user goes idle, Scans day's transcripts for new info, Prunes verbose/outdated memories, Detects drifted existing memories

Operational Details

Prompt Cache Economics

Static system prompt cached globally, DYNAMIC_BOUNDARY splits cached vs session, 14 cache-break vectors tracked

Anti-Distillation

ANTI_DISTILLATION_CC flag, Injects fake tool definitions via API, Server-side summary + crypto signatures

Frustration Detection

Regex-based profanity matching, Faster + cheaper than inference call, userPromptKeywords.ts

Circuit Breaker

MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3, Fixed 250K wasted API calls/day, Three lines of code

Terminal Renderer

Int32Array ASCII char pool, Bitmask-encoded style metadata, Patch optimiser merges cursor moves

A/B Tested Verbosity

~1.2% output token reduction, 'Keep text between tool calls to ≤25 words', Numbers beat vibes

Package Map

claude-code/ (512,000+ lines TypeScript)
├── QueryEngine.ts            ~46,000 lines — LLM plumbing
├── Tool.ts                   ~29,000 lines — 40+ tool definitions
├── bash-security/            ~9,700 lines — 22 validators + AST parser
├── coordinatorMode.ts        Multi-agent orchestration-as-prompt
├── verificationAgent.ts      Adversarial verification (distrusts builder)
├── promptCache*.ts           14 cache-break detectors + sticky latches
├── contextCompaction.ts      Second Claude for summarisation
├── memory/                   MEMORY.md + CLAUDE.md + AutoDream
├── kairos/                   Autonomous daemon (unreleased)
├── terminal/                 Game-engine inspired TUI renderer
├── plugins/                  Plugin marketplace + MCP integration
├── telemetry/                Sentry + PostHog + usage tracking
└── anti-distillation/        Fake tools + summary signatures

The Architectural Insight

Claude Code's load-bearing design decision is separating decision from permission. The model proposes actions; the tool system — with 9,700 lines of bash security, 22 validators, and tree-sitter AST parsing — decides what is allowed. Permission gates live outside the model's inference path. This isn't a suggestion system. It's a security architecture. And behind it all, KAIROS hints at where Anthropic is heading: not a coding assistant you talk to, but an autonomous agent that works while you sleep.

← cd ../architectures