Dive into Claude Code

<p align="center"> <img src="./assets/main_structure.png" width="85%" alt="High-level system structure of Claude Code"> </p> <p align="center"> <a href="./paper/Dive_into_Claude_Code.pdf"><img src="https://img.shields.io/badge/Paper-PDF-blue.svg?logo=adobeacrobatreader&logoColor=white" alt="Paper"></a> <a href="https://arxiv.org/abs/2604.14228"><img src="https://img.shields.io/badge/arXiv-2604.14228-b31b1b.svg" alt="arXiv"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/License-CC--BY--NC--SA--4.0-lightgrey.svg" alt="License"></a> <a href="https://github.com/VILA-Lab/Dive-into-Claude-Code/stargazers"><img src="https://img.shields.io/github/stars/VILA-Lab/Dive-into-Claude-Code?style=social" alt="Stars"></a> <a href="#contributing"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a> </p> <p align="center"> <b>English</b> | <a href="./README_zh.md">中文</a> </p>

A comprehensive source-level architectural analysis of Claude Code (v2.1.88, ~1,900 TypeScript files, ~512K lines of code), combined with a curated collection of community analyses, a design-space guide for agent builders, and cross-system comparisons.

[!TIP] TL;DR -- Only 1.6% of Claude Code's codebase is AI decision logic. The other 98.4% is deterministic infrastructure -- permission gates, context management, tool routing, and recovery logic. The agent loop is a simple while-loop; the real engineering complexity lives in the systems around it. This repo dissects that architecture and distills it into actionable design guidance for anyone building AI agent systems.

---

Table of Contents

From Our Paper

• 🌟 Key Highlights
• 📖 Reading Guide
• 🏗️ Architecture at a Glance
• 🧭 Values and Design Principles
• 🔄 The Agentic Query Loop
• 🛡️ Safety and Permissions
• 🧩 Extensibility
• 🧠 Context and Memory
• 👥 Subagent Delegation
• 💾 Session Persistence

Beyond the Paper

• 🛰️ New Signals in the Agent Design Space
• 🛠️ Build Your Own AI Agent: A Design Guide
• ⚖️ Cross-System Comparison: Claude Code vs OpenClaw vs Hermes-Agent
• 🔎 Find Resources by Design Question
• 🌐 Community Projects & Research
• 🚀 Other Notable AI Agent Projects
• 🤝 Contributing
• 🔖 Citation

---

Key Highlights

• 98.4% Infrastructure, 1.6% AI -- The agent loop is a simple while-loop; the real complexity is permission gates, context management, and recovery logic.
• 5 Values → 13 Principles → Implementation -- Every design choice traces back to human authority, safety, reliability, capability, and adaptability.
• Defense in Depth with Shared Failure Modes -- 7 safety layers, but all share performance constraints. 50+ subcommands bypass security analysis.
• 2 CVEs Reveal a Pre-Trust Window -- Extensions execute before the trust dialog appears.
• The Cross-Cutting Harness Resists Reimplementation -- The loop is easy to copy; hooks, classifier, compaction, and isolation are not.

---

Reading Guide

| If you are a... | Start here | Then read | |:----------------|:-----------|:----------| | Agent Builder | Build Your Own Agent | Architecture Deep Dive | | Security Researcher | Safety and Permissions | Architecture: Safety Layers | | Product Manager | Key Highlights | Values and Principles | | Researcher | Full Paper (arXiv) | Community Resources |

1,884 files · ~512K lines · v2.1.88 · 7 safety layers · 5 compaction stages · 54 tools · 27 hook events · 4 extension mechanisms · 7 permission modes

---

<details open> <summary><h2>Architecture at a Glance</h2></summary>

Claude Code answers four design questions that every production coding agent must face:

| Question | Claude Code's Answer | |:---------|:---------------------| | Where does reasoning live? | Model reasons; harness enforces. ~1.6% AI, 98.4% infrastructure. | | How many execution engines? | One queryLoop for all interfaces (CLI, SDK, IDE). | | Default safety posture? | Deny-first: deny > ask > allow. Strictest rule wins. | | Binding resource constraint? | ~200K (older models) / 1M (Claude 4.6 series) context window. 5 compaction layers before every model call. |

The system decomposes into 7 components (User → Interfaces → Agent Loop → Permission System → Tools → State & Persistence → Execution Environment) across 5 architectural layers.

<p align="center"> <img src="./assets/layered_architecture.png" width="100%" alt="5-layer subsystem decomposition"> </p>

[!NOTE] For the full architectural deep dive -- 7 safety layers, 9-step turn pipeline, 5-layer compaction, and more -- see docs/architecture.md.

<p align="right"><a href="#dive-into-claude-code">↑ Back to top</a></p> </details>

---

<details> <summary><h2>Values and Design Principles</h2></summary>

The architecture traces from 5 human values through 13 design principles to implementation:

| Value | Core Idea | |:------|:----------| | Human Decision Authority | Humans retain control via principal hierarchy. When a 93% prompt-approval rate revealed approval fatigue, response was restructured boundaries, not more warnings. | | Safety, Security, Privacy | System protects even when human vigilance lapses. 7 independent safety layers. | | Reliable Execution | Does what was meant. Gather-act-verify loop. Graceful recovery. | | Capability Amplification | "A Unix utility, not a product." 98.4% is deterministic infrastructure enabling the model. | | Contextual Adaptability | CLAUDE.md hierarchy, graduated extensibility, trust trajectories that evolve over time. |

<details> <summary><b>The 13 Design Principles</b></summary>

| Principle | Design Question | |:----------|:----------------| | Deny-first with human escalation | Should unrecognized actions be allowed, blocked, or escalated? | | Graduated trust spectrum | Fixed permission level, or spectrum users traverse over time? | | Defense in depth | Single safety boundary, or multiple overlapping ones? | | Externalized programmable policy | Hardcoded policy, or externalized configs with lifecycle hooks? | | Context as scarce resource | Single-pass truncation or graduated pipeline? | | Append-only durable state | Mutable state, snapshots, or append-only logs? | | Minimal scaffolding, maximal harness | Invest in scaffolding or operational infrastructure? | | Values over rules | Rigid procedures or contextual judgment with deterministic guardrails? | | Composable multi-mechanism extensibility | One API or layered mechanisms at different costs? | | Reversibility-weighted risk assessment | Same oversight for all, or lighter for reversible actions? | | Transparent file-based config and memory | Opaque DB, embeddings, or user-visible files? | | Isolated subagent boundaries | Shared context/permissions, or isolation? | | Graceful recovery and resilience | Fail hard, or recover silently? |

</details>

The paper also applies a sixth evaluative lens -- long-term capability preservation -- citing evidence that developers in AI-assisted conditions score 17% lower on comprehension tests.

<p align="right"><a href="#dive-into-claude-code">↑ Back to top</a></p> </details>

---

<details> <summary><h2>The Agentic Query Loop</h2></summary> <p align="center"> <img src="./assets/iteration.png" width="60%" alt="Runtime turn flow"> </p>

The core is a ReAct-pattern while-loop: assemble context → call model → dispatch tools → check permissions → execute → repeat. Implemented as an AsyncGenerator yielding streaming events.

Before every model call, five compaction shapers run sequentially (cheapest first): Budget Reduction → Snip → Microcompact → Context Collapse → Auto-Compact.

9-step pipeline per turn: Settings resolution → State init → Context assembly → 5 pre-model shapers → Model call → Tool dispatch → Permission gate → Tool execution → Stop condition

Two execution paths:

• StreamingToolExecutor -- begins executing tools as they stream in (latency optimization)
• Fallback runTools -- classifies tools as concurrent-safe or exclusive

Recovery: Max output token escalation (3 retries), reactive compaction (once per turn), prompt-too-long handling, streaming fallback, fallback model

5 stop conditions: No tool use, max turns, context overflow, hook intervention, explicit abort

<p align="right"><a href="#dive-into-claude-code">↑ Back to top</a></p> </details>

---

<details> <summary><h2>Safety and Permissions</h2></summary> <p align="center"> <img src="./assets/permission.png" width="75%" alt="Permission gate"> </p>

7 permission modes form a graduated trust spectrum: plan → default → acceptEdits → auto (ML classifier) → dontAsk → bypassPermissions (+ internal bubble).

Deny-first: A broad deny always overrides a narrow allow. 7 independent safety layers from tool pre-filtering through shell sandboxing to hook interception. Permissions are never restored on resume -- trust is re-established per session.

[!WARNING] Shared failure modes: Defense-in-depth degrades when layers share constraints. Per-subcomman