Dive into Claude Code

The Design Space of Today’s and Future AI Agent Systems

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
• 🤝 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.
• Bounded Analysis with an Approval Fallback – In the legacy shell-parser path, more than 50 subcommands triggers an ask decision.
• 2 CVEs Revealed a Pre-Trust Window – In earlier releases, MCP servers and settings environment variables took effect before the user accepted the trust dialog.
• 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 architecture sections describe Claude Code v2.1.88. The design guide and resource catalog extend that analysis with work reviewed through October 6, 2026, and Claude Code and Codex release notes checked through October 14, 2026. The main PDF link opens arXiv v3, October 10, 2026, which redraws the layered architecture (Figure 3) and the context figure (Figure 6) and clarifies resume and pre-trust behavior. arXiv v2 and the April 2026 repository PDF remain available as archives.

---

---

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 resource type.

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

---

---

---

Contributing

Contributions are welcome — this space moves fast, and things slip past us.

If you come across a paper, blog post, repository, benchmark, or security write-up worth adding, feel free to open a pull request or an issue.

Citation

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

License

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