Dive into Claude Code

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

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

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 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

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-subcommand parsing causes event-loop starvation -- commands exceeding 50 subcommands bypass security analysis entirely to prevent the REPL from freezing.

Authorization pipeline: Pre-filtering (strip denied tools) → PreToolUse hooks → Deny-first rule evaluation → Permission handler (4 branches: coordinator, swarm worker, speculative classifier, interactive)

Auto-mode classifier (yoloClassifier.ts): Separate LLM call with internal/external permission templates. Two-stage: fast-filter + chain-of-thought.

Pre-trust execution window: 2 patched CVEs share this root cause -- hooks and MCP servers execute during initialization before the trust dialog appears, creating a structurally privileged attack window outside the deny-first pipeline.

Four mechanisms at graduated context costs: Hooks (zero) → Skills (low) → Plugins (medium) → MCP (high). Three injection points in the agent loop: assemble() (what the model sees), model() (what it can reach), execute() (whether/how actions run).

Tool pool assembly (5-step): Base enumeration (up to 54 tools) → Mode filtering → Deny pre-filtering → MCP integration → Deduplication

27 hook events across 5 categories with 4 execution types (shell, LLM-evaluated, webhook, subagent verifier)

Plugin manifest accepts 10 component types: commands, agents, skills, hooks, MCP servers, LSP servers, output styles, channels, settings, user config

Skills: SKILL.md with 15+ YAML frontmatter fields. Key difference -- SkillTool injects into current context; AgentTool spawns isolated context.

9 ordered sources build the context window. CLAUDE.md instructions are delivered as user context (probabilistic compliance), not system prompt (deterministic). Memory is file-based (no vector DB) -- fully inspectable, editable, version-controllable.

4-level CLAUDE.md hierarchy: Managed (/etc/) → User (~/.claude/) → Project (CLAUDE.md, .claude/rules/) → Local (CLAUDE.local.md, gitignored)

5-layer compaction (graduated lazy-degradation): Budget reduction → Snip → Microcompact → Context Collapse (read-time projection, non-destructive) → Auto-Compact (full model summary, last resort)

Memory retrieval: LLM-based scan of memory-file headers, selects up to 5 relevant files. No embeddings, no vector similarity.

6 built-in types (Explore, Plan, General-purpose, Guide, Verification, Statusline) + custom agents via .claude/agents/*.md. Sidechain transcripts: only summaries return to parent (parent's context is protected from subagent verbosity). Three isolation modes: worktree, remote, in-process. Coordination via POSIX flock().

SkillTool vs AgentTool: SkillTool injects into current context (cheap). AgentTool spawns isolated context (expensive, but prevents context explosion).

Permission override: Subagent permissionMode applies UNLESS parent is in bypassPermissions/acceptEdits/auto (explicit user decisions always take precedence).

Custom agents: YAML frontmatter supports tools, disallowedTools, model, effort, permissionMode, mcpServers, hooks, maxTurns, skills, memory scope, background flag, isolation mode.

Three channels: append-only JSONL transcripts, global prompt history, subagent sidechains. Permissions never restored on resume -- trust is re-established per session. Design favors auditability over query power.

Chain patching: Compact boundaries record headUuid/anchorUuid/tailUuid. The session loader patches the message chain at read time. Nothing is destructively edited on disk.

Checkpoints: File-history checkpoints for --rewind-files, stored at ~/.claude/file-history/<sessionId>/.

New agent-system developments reinforce the same lesson Claude Code makes clear: agent capability is not a model property alone. It comes from the runtime, context layer, execution boundary, tool supply chain, the controls humans have over it, and the evaluation loop around the model.

These signals do not replace Claude Code's design space; they make its boundaries clearer. The agent loop is the small part. The harness around it is where most capability, safety, and reliability decisions now live. For month-level source notes, see docs/agent-design-space-source-notes.md.

Not a coding tutorial. A guide to the design decisions you must make, derived from architectural analysis.

Every production agent must navigate these decisions:

Read the full guide: docs/build-your-own-agent.md

The same recurring design questions admit different architectural answers when the deployment context changes. The table below contrasts Claude Code v2.1.88 with two notable peers — OpenClaw, a local-first multi-channel personal-assistant gateway, and NousResearch/hermes-agent, a self-improving multi-deployment agent — across the six design dimensions Section 10 of the paper uses for the OpenClaw comparison. Cells are source-grounded; this is not a feature scoreboard.

Design Dimension	Claude Code (v2.1.88)	OpenClaw	Hermes-Agent
System scope & deployment	Per-user CLI / SDK / IDE interface for coding; one queryLoop async generator across entry points.	Local-first WebSocket gateway (default port 18789, loopback-bound by default; other binds available); routes ~23 messaging channels to an embedded agent runtime; companion apps for macOS, iOS, Android.	Three entry points: hermes (interactive CLI), hermes-agent (programmatic runtime), hermes-acp (ACP server); gateway adapters route messages to per-session AIAgent instances cached LRU-style (max 128, 1 h idle TTL); also runs as MCP server via hermes mcp serve.
Trust model & security	Deny-first per-action evaluation; 7 permission modes; LLM-based auto-mode classifier (yoloClassifier / sideQuery); session-scoped permission state (session bypass flag, app allowlist state) is not restored on resume.	Single trusted operator per gateway; DM pairing codes, sender allowlists, gateway authentication; per-agent allow / deny tool policy; opt-in sandboxing via Docker / SSH / OpenShell, off by default; non-main mode sandboxes only non-main sessions; hostile multi-tenant isolation explicitly not supported.	Dangerous-command pattern detection with per-session approval state; CLI interactive prompts and gateway async prompts; auxiliary-LLM smart approval auto-approves low-risk commands; permanent allowlist persisted in config.yaml; subagent worker threads default to auto-deny dangerous commands (opt-in subagent_auto_approve for batch / cron runs).
Agent runtime & tools	Single queryLoop async generator with streamed event yields; environment- and feature-gated tool registry; before-API compaction (Snip, Microcompact, Context Collapse, Auto-Compact) runs conditionally, with Auto-Compact first attempting session-memory compaction.	Embedded agent runtime inside the gateway's RPC dispatch (the agent RPC validates parameters, accepts immediately, runs asynchronously, and streams lifecycle / stream events back over the gateway protocol); per-session queue serialization with an optional global lane.	While-loop with explicit per-turn iteration budget and grace-call slot; per-turn checkpoint dedup; gateway step_callback hook fires on each iteration; auxiliary-model context compression summarizes middle turns while protecting head and tail.
Extension architecture	Four mechanisms at graduated context cost: hooks → skills → plugins → MCP; 27 hook events; 10 plugin component types.	Manifest-first plugin system with 12 documented capability categories; central registry exposes tools, channels, provider setup, hooks, HTTP routes, CLI commands, services; separate skills layer with multiple sources (workspace highest precedence) plus the ClawHub public registry; openclaw mcp provides both an MCP server interface and an outbound client registry for other MCP servers.	12 bundled plugins under plugins/ (context_engine, disk-cleanup, example-dashboard, google_meet, hermes-achievements, image_gen, kanban, memory, observability, platforms, spotify, strike-freedom-cockpit); MCP server (mcp_serve.py) exposes 10 tools; ACP adapter (acp_adapter/) exposes Hermes as an ACP server.
Memory & context	4-level CLAUDE.md hierarchy; before-API compaction (Snip, Microcompact, Context Collapse, Auto-Compact); LLM-based selection from file-based Markdown memory files.	Workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md) plus conditional BOOTSTRAP.md / HEARTBEAT.md / MEMORY.md; separate memory system (MEMORY.md, daily notes under memory/YYYY-MM-DD.md, optional DREAMS.md); hybrid vector + keyword search when an embedding provider is configured; experimental dreaming for long-term promotion; pluggable compaction providers.	SQLite state store with FTS5 full-text search and WAL-mode concurrent readers; sessions linked by parent_session_id chains for compression-triggered splits; 8 swappable memory backends under plugins/memory/ (byterover, hindsight, holographic, honcho, mem0, openviking, retaindb, supermemory); auxiliary-LLM compression as a separate context-management layer.
Multi-agent architecture	Sub-agent delegation via sidechain transcripts; 6 built-in agent definitions (availability conditional on build / mode) plus custom; a single summary message returns to parent (in-process / viewable transcript cases preserve more internal detail); agent-isolation settings include worktree and remote, with an in-process teammate backend in the swarm path.	Two layers. (1) Multi-agent routing: per-channel isolated agents with their own workspace, auth profiles, session store, and model configuration, dispatched via deterministic binding rules. (2) Sub-agent delegation: maxSpawnDepth range 1–5, default 1, recommended 2; tool policy varies by depth; project vision (VISION.md) rejects agent-hierarchy frameworks as the default.	delegate_task tool spawns child AIAgent instances in a ThreadPoolExecutor (parent blocks until children complete); each child has fresh conversation history, its own task_id, and a restricted toolset (DELEGATE_BLOCKED_TOOLS strips delegate_task, clarify, memory, send_message, execute_code); default depth MAX_DEPTH = 1 (configurable up to cap 3); default 3 concurrent children.

What this contrast reveals. Three observations follow from the table. First, deployment context drives the rest of the design: a per-user coding CLI converges on per-action approval and a single execution loop, a multi-channel gateway converges on perimeter trust and channel-bound agents, and a multi-deployment messaging-and-cloud agent converges on opt-in container/cloud isolation, an LLM-based smart approval, and a swappable-backend memory layer. Second, the extension layer is where each system most clearly differentiates: Claude Code stratifies four mechanisms by context cost, OpenClaw treats extension as registry-managed capabilities at the gateway, and Hermes-Agent ships bundled plugins plus dual MCP server / ACP server interfaces other agents can connect to. Third, memory architectures sit on a spectrum: file-based and inspectable Markdown (Claude Code), file-based plus optional vector + experimental dreaming (OpenClaw), or full-text indexed (FTS5) plus eight swappable plugin backends including dedicated vector / RAG providers (Hermes-Agent). The table is best read not as a scoreboard but as three different fixed points in the same design space.

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.

A curated map of the repos, reimplementations, and academic papers surrounding Claude Code's architecture.

Official Anthropic Resources

Primary sources referenced throughout the paper — Anthropic's own engineering and research publications, plus product documentation.

Research & Engineering Blogs

Product Documentation