Dive into Claude Code

English | 中文

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
• 🔖 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.
• 4 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

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

---

---

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.

↑ Back to top

---

---

↑ Back to top

---

---

---

---

---

---

---

---

Find Resources by Design Question

The sections above give Claude Code’s own answer to each design question. The catalogs below are organized by resource type instead. This table joins the two, so you can start from a question rather than from a file format.

For shifts that cut across every axis rather than sitting on one, see New Signals in the Agent Design Space.

---

---

---

Citation

@article{diveclaudecode2026,
  title={Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems},
  author={Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, and Zhiqiang Shen},
  year={2026},
  eprint={2604.14228},
  archivePrefix={arXiv},
  primaryClass={cs.SE},
}

License

This work is licensed under CC BY-NC-SA 4.0.