Claude Code Internals

A comprehensive architectural analysis of Claude Code — Anthropic's official CLI coding agent.

Based on reverse-engineered compiled source. 39 documents covering ~17,000 lines of analysis across 8 subsystems.

中文文档

---

What This Is

This project provides an in-depth architectural dissection of Claude Code's internal design. Every major subsystem has been analyzed at the function-signature level — not surface-level overviews, but implementation-grade documentation that enables reconstruction.

What you'll learn:

• How the agent loop works (state machine, 7 transition reasons, pre-API pipeline)
• How context management prevents window overflow (6-layer defense, autocompact, microcompact)
• How the tool system is built (40+ tools, Zod schemas, streaming execution)
• How bash commands are secured (23K lines of parser + security engine)
• How multi-agent coordination works (leader-worker, 4 backend types, permission sync)
• How plugins extend the system (marketplace, MCPB, lifecycle management)
• How memory persists across sessions (3-layer architecture, forked agent extraction)

Who This Is For

You are...	Start here
Building an agent framework	Architecture → Context Management → Tool System
Interested in security	Security → Bash parser + security engine
Building a plugin system	Plugin System → loader + marketplace
Working on multi-agent	Agent System → swarm + backends + permissions
Debugging Claude Code	Support Systems → memory + skills

Structure

docs/
├── en/                          # English
│   ├── architecture/            # Entry points, agent loop, API, prompt assembly
│   ├── context-management/      # Token budget, compaction, caching
│   ├── tool-system/             # Tool registration, execution, bash security
│   ├── security/                # Permission pipeline, stop hooks
│   ├── agent-system/            # Multi-agent: swarm, backends, tasks, spawning
│   ├── plugin-system/           # Plugin loader, marketplace, schemas
│   └── support-systems/         # Memory, skills
└── zh-CN/                       # Chinese (中文)
    └── (same structure)

Architecture

The heart of Claude Code: how the agent loop processes requests, calls the API, and handles tool use.

Document	What it covers
Startup Sequence	From node main.tsx to first user input. Ghost parallelism, feature gates, deferred prefetches.
Agent Loop	The while(true) state machine. 7 transition reasons, pre-API pipeline, streaming tool executor.
API Call Mechanics	Raw Stream (not SDK), 3-layer fallback, thinking config, model selection.
Input → Output Chain	User input → message creation → normalization → API format.
System Prompt Assembly	19 sections, static/dynamic boundary, cache-aware splitting.
Model Request Chain	Config file system, model selection, provider adaptation, OAuth auth, full request pipeline.

Context Management

How Claude Code manages the context window without hitting limits. Six layers of defense, escalating from cheap to expensive.

Document	What it covers
Overview	Architecture, feature flags, design decisions, known traps.
Pre-API Pipeline	The 6-layer defense: budget → snip → microcompact → collapse → autocompact → hard wall.
Microcompact	Time-based, cached, and API microcompact variants.
Autocompact	Full summarization, prompt design, PTL retry, session memory compact.
Message Grouping	API round grouping by message.id boundaries.
Token Budget	3-layer token management: tool budget / task budget / context window.
Prompt Cache	Cache breakpoints, break detection, 1h TTL, cached microcompact.

Tool System

From tool definition to execution. Includes a 23K-line bash security subsystem.

Document	What it covers
Tool Registration	buildTool() factory, getTools() assembly, Zod→JSON Schema serialization.
Tool Execution	runTools(), StreamingToolExecutor, permission checks, abort propagation.
Bash Parser	4,436-line hand-written recursive descent parser, tokenizer, AST generation.
Bash AST	Fail-closed argv extraction, variable tracking, dangerous type blacklist.
Bash Heredoc	Heredoc extraction, pipe processing, nested structure handling.
Bash Commands	Command registry, prefix extraction, policy spec.
Bash Security Engine	23 security checks, misparsing defense, heredoc security.
Bash Permissions	12-step permission flow, rule matching, classifier system.
Bash Validation	Read-only whitelist, path access control, sed validation.
Shell Provider	Bash vs PowerShell (8 dimensions), shell snapshots, sandbox decisions.

Security

Cross-cutting security concerns: permission decisions, safety hooks.

Document	What it covers
Permission Pipeline	5-step sequential check, interactive handler (5-way race), YOLO classifier, bypass-immune safety checks.
Stop Hooks	Post-response pipeline: memory extraction, auto-dream, shell hooks, blocking errors.

Agent System

Multi-agent coordination: how Claude Code runs parallel workers.

Document	What it covers
Swarm Overview	Leader-worker model, 4 backend types, data flow diagrams.
InProcess Runner	AsyncLocalStorage isolation, message priority queues, compaction context.
Execution Backends	InProcess / Tmux / Pane / iTerm backends, detection logic.
Swarm Permissions	LeaderPermissionBridge, file system + mailbox dual-track, preserveMode.
Task System	7 task types, stall watchdog, stable idle, notification atomicity.
Spawn Lifecycle	Spawn flow, CLI flag inheritance, TeamFile, reconnection, cleanup.

Plugin System

How Claude Code becomes a platform: plugin loading, marketplace, lifecycle management.

Document	What it covers
Plugin Loader	3 sources (session > marketplace > builtin), dual loader + warm cache.
Plugin Injection	Commands / hooks / agents / output styles injection, namespace rules.
Plugin Operations	Install / uninstall / update lifecycle, scope array, non-in-place updates.
Marketplace	GCS CDN + git fallback, SSH/HTTPS detection, 3-layer conflict resolution.
Installation	MCPB handling, ZIP cache, MCP integration, auto-update.
Plugin Schemas	15+ schema definitions, 9 marketplace sources, 3-layer anti-spoofing.
Plugin Infrastructure	18 utility modules, 5-layer settings priority, reconciler.

Support Systems

Memory, skills, and other supporting infrastructure.

Document	What it covers
Memory System	3-layer architecture (context / session / memdir), forked agent extraction, Sonnet-based relevance selection.
Skills System	7 loading sources, SKILL.md frontmatter, change detection, conditional skills.

Key Findings

Across all 39 documents, the most interesting architectural decisions:

1. The agent loop is a pure state machine — each iteration destructures a State object, processes it, and writes a new State at the continue site. 7 distinct transition reasons drive re-entry.

2. Context management has 6 layers of defense — each escalating from cheap (truncate tool results) to expensive (full summarization). Most turns only reach layer 2-3.

3. The bash parser is 7K lines of hand-written code — not because they couldn't use a library, but because they needed byte-identical AST output for differential testing against tree-sitter.

4. Security is fail-closed everywhere — unknown AST node types → too-complex → ask user. Unknown plugin sources → reject. Unknown tool permissions → deny.

5. Multi-agent uses 3 different isolation strategies — in-process (shared memory), tmux (process isolation), pane (terminal isolation). Each trades off latency vs safety.

6. Plugins can inject anything — commands, hooks, agents, skills, MCP servers, output styles. The plugin system is the extensibility story.

7. Memory uses Sonnet for relevance, not embeddings — descriptive judgment is more accurate than vector distance for this use case.

8. The startup has ghost parallelism — MDM, keychain, and API preconnect run during the ~135ms module evaluation period, saving 200-300ms.

Methodology

All analysis is based on decompiled/compiled TypeScript source from Claude Code. Each document was produced by:

1. Reading the relevant source files completely (no skimming)
2. Documenting every function signature, type definition, and data structure
3. Tracing data flow through the code
4. Identifying design decisions and their trade-offs
5. Cross-referencing between modules to verify consistency

No source code is included in this repository — only analysis documents.

Contributing

This is a snapshot analysis. If Claude Code's source changes significantly, the documents may become outdated. Contributions to update or correct the analysis are welcome.

License

This analysis is provided for educational and research purposes.

---

Analysis completed April 2026. Based on Claude Code compiled source.