Dive into Claude Code

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

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.

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

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

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

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

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.

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 a model call, context management considers five stages in order: Budget Reduction → Snip → Microcompact → Context Collapse → Auto-Compact. Feature gates, settings, and thresholds determine which stages change the context.

9-step pipeline per turn: Settings resolution → State init → Context assembly → Conditional context management → 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 overfl