Dive into Claude Code — Architecture Deep Dive

• Source ID: src-20260423-115cbc011543
• Kind: analysis
• Scope: shared
• Origin: https://github.com/VILA-Lab/Dive-into-Claude-Code/blob/main/docs/architecture.md
• Raw path: sources/raw/dive-into-claude-code-architecture-deep-dive__src-20260423-115cbc011543.md
• Status: active

Tags

community-analysis academic-paper architecture

Content

Back to Main README

Architecture Overview

The core agent loop is a simple while-loop. Most of the code lives in the systems around it.

Four Design Questions Every Coding Agent Must Answer

High-Level System Structure (7 Components)

1. User -- Submits prompts, approves permissions, reviews output
2. Interfaces -- Interactive CLI, headless CLI (claude -p), Agent SDK, IDE/Desktop/Browser
3. Agent Loop -- queryLoop async generator in query.ts: model call → tool dispatch → result collection → repeat
4. Permission System -- Deny-first rules + auto-mode ML classifier + hook interception
5. Tools -- Up to 54 built-in + MCP-provided, assembled via assembleToolPool
6. State & Persistence -- Append-only JSONL transcripts, prompt history, subagent sidechains
7. Execution Environment -- Shell (with sandbox), filesystem, web fetching, MCP connections

All interfaces converge on the same queryLoop -- the interactive CLI, headless mode, SDK, and IDE all share the same code path. QueryEngine is a conversation wrapper, not the engine itself.

5-Layer Subsystem Decomposition (21 Subsystems)

Seven Independent Safety Layers

A request must pass through all applicable layers -- any single layer can block it:

1. Tool pre-filtering -- Blanket-denied tools removed from model's view entirely
2. Deny-first rule evaluation -- Deny always overrides allow, even when allow is more specific
3. Permission mode constraints -- Active mode determines baseline handling
4. Auto-mode ML classifier -- Separate LLM call evaluating safety independently
5. Shell sandboxing -- Filesystem + network isolation for shell commands
6. Non-restoration on resume -- Permissions never persist across session boundaries
7. Hook-based interception -- PreToolUse hooks can modify or block actions

Turn Execution: 9-Step Pipeline

Each turn follows a 9-step pipeline:

1. Settings resolution → 2. State initialization → 3. Context assembly → 4. Five pre-model shapers → 5. Model call → 6. Tool dispatch → 7. Permission gate → 8. Tool execution → 9. Stop condition check

Five Pre-Model Context Shapers

Executed sequentially before every model call, cheapest first:

Recovery Mechanisms

• Max output token escalation (up to 3 retries per turn)
• Reactive compaction (fires at most once per turn)
• Prompt-too-long: tries context-collapse overflow → reactive compaction → terminate
• Streaming fallback and fallback model switching

Permission System Deep Dive

7 Permission Modes

Authorization Pipeline

4-stage flow: Pre-filtering (strip denied tools from model's view) → PreToolUse hooks (can return permissionDecision) → Rule evaluation (deny-first) → Permission handler (4 branches: coordinator, swarm worker, speculative classifier, interactive)

Auto-Mode Classifier

yoloClassifier.ts: loads base system prompt + permission templates (separate internal/external). Two-stage evaluation: fast-filter + chain-of-thought. Races pre-computed classification against a timeout.

Extensibility: MCP, Plugins, Skills, and Hooks

Four Extension Mechanisms (Graduated Context Cost)

Tool Pool Assembly (5-step pipeline)

Base enumeration (up to 54 tools) → Mode filtering → Deny rule pre-filtering → MCP integration → Deduplication

Three Injection Points

• assemble() -- What the model sees: CLAUDE.md, skill descriptions, MCP resources, hook-injected context
• model() -- What the model can reach: built-in tools, MCP tools, SkillTool, AgentTool
• execute() -- Whether/how an action runs: permission rules, PreToolUse/PostToolUse hooks, Stop hooks

Context Construction and Memory

9 Ordered Context Sources

System prompt → Environment info → CLAUDE.md hierarchy → Path-scoped rules → Auto-memory → Tool metadata → Conversation history → Tool results → Compact summaries

CLAUDE.md Hierarchy (4 Levels)

Critical design choice: CLAUDE.md is user context (probabilistic compliance), NOT system prompt (deterministic). Permission rules provide the deterministic enforcement layer.

File-Based Memory

• No embeddings, no vector DB -- uses LLM-based scan of memory-file headers
• Selects up to 5 relevant files on demand
• Fully inspectable, editable, version-controllable by the user

Subagent Delegation

6 Built-in Types + Custom Agents

Built-in: Explore, Plan, General-purpose, Claude Code Guide, Verification, Statusline-setup.

Custom: .claude/agents/*.md with YAML frontmatter supporting tools, model, permissions, hooks, skills, and more.

Key Design: SkillTool vs AgentTool

• SkillTool: Injects instructions into current context (cheap, same window)
• AgentTool: Spawns new isolated context window (expensive, ~7x tokens, but context-safe)

Three Isolation Modes

Sidechain Transcripts

Each subagent writes its own .jsonl file. Only summary returns to parent. Full history never enters parent context. Multi-instance coordination via POSIX flock() -- zero external dependencies.

Session Persistence

Three Persistence Channels

Safety: Permissions Never Restored on Resume

Trust is always re-established in the current session. This accepts user friction as the cost of maintaining the safety invariant.

Design Trade-off

Append-only JSONL favors auditability and simplicity over query power. Every event is human-readable, version-controllable, and reconstructable without specialized tooling.