Source Analysis

What actually happens when you type a message into Claude Code?

Based on the @anthropic-ai/claude-code 2.1.88 npm release (since removed from npm history), reverse-engineered through source map → path statistics → semantic layering → cross-validation. Dissecting an industrial-grade agent harness system containing 1,902 source files, 43 tools, and 97 commands.

Start Here

Deep Dives

Reading Paths

Different backgrounds call for different entry points. Pick the path that fits your goals:

Path 1: User Perspective

Understand why Claude Code behaves the way it does — why tools get denied, why long sessions compress, why some commands are hidden.

1. Runtime Loop — follow a request through seven stages
2. Execution Governance — understand the allow/deny decision chain
3. Command Surface — find the internal mapping for commands you use
4. Cost Tracking — understand token metering and compression triggers

Path 2: Agent Builder

Extract reusable design patterns from an industrial-grade agent system — query loop, tool governance, context compaction, memory loops.

1. Architecture Map — establish the six-layer structure
2. Runtime Loop — understand the query loop heartbeat and state machine
3. Tool Plane — understand tool registration, governance, and execution model
4. Memory System — understand five-layer compression and long-session continuity
5. Coordinator Mode — understand multi-Worker orchestration

Path 3: Reverse Engineering Researcher

Fully map the system’s capability boundaries and evolution direction — from stable trunk to experimental edges.

1. Architecture Map — reduce 1,902 files to six structural layers
2. Tool Plane + Command Surface — full capability surface scan
3. Signals & Extensions — identify mature vs. experimental capabilities
4. All Deep Dive pages — verify source path evidence one by one

General Advice

Regardless of path, use the Visual Map alongside the docs — docs explain why things are designed this way, the visual map answers where they are and how they connect.

How to read this alongside official materials

Official materials are best for confirming feature definitions, supported boundaries, and minimal examples. The source-analysis section is better for understanding how the system is organized, why those constraints exist, and which patterns are worth carrying into your own agent engineering.

Recommended order:

1. Use official docs to confirm capability primitives and current boundaries
2. Read Research Method to establish the frame
3. Then move into Runtime Loop and Tool Plane
4. Use Engineering Playbook to reorganize those capabilities into a rollout path
5. Finally treat Memory System, Coordinator Mode, and MCP & Bridge as transferable engineering samples

This avoids two common misreads: taking official minimal examples as complete system design, or treating local signals in a single source snapshot as long-term product commitments.

Key Findings

Claude Code is not a simple LLM wrapper CLI. The 1,902 source files reverse-engineered from the source map reveal a carefully designed agent harness system — the model is just one unreliable component, surrounded by a complete outer-loop orchestration:

1. query loop is the heartbeat: a while(true) loop (query.ts lines 241-1728) driving “sample → tool → permission → recover/continue/stop” cycles
2. tools are managed interfaces, not bare functions: 43 tools registered through Tool.ts, each declaring readonly, concurrencySafe, sandboxed traits, passing through four governance layers before execution
3. context is not unlimited: five-layer compression (Micro → TimeBased → APISide → SessionMemory → Full) triggers automatically at ~93% token threshold
4. memory lives beyond transcripts: CLAUDE.md, memdir, SessionMemory, daily logs collectively maintain cross-session continuity
5. security is not an add-on layer: permission modes, rule matching, hook interception, OS-level sandboxing are architecturally embedded in the execution path
6. sub-agents are not “just another agent”: 6 built-in sub-agent types, each with independent toolsets and isolation strategies

Four Runtime Invariants

Reading source by directory gives you a feature list. What actually holds the runtime together are four invariants that must hold simultaneously — understanding these matters more than understanding any single module:

The value of these invariants: what’s worth migrating to your own agent design is not a specific function, but which invariant it’s paying for.

Lessons for Agent Builders

Claude Code’s source is not just a product implementation — it’s a reference sample for Agent Harness Engineering. Design principles you can directly adopt:

Cognitive Science in the Source

Claude Code’s design is not purely engineering — some decisions are deeply influenced by cognitive science (credited to Anthropic’s Character Lead, Amanda Askell):

• Memory filtering: The system doesn’t mechanically store all conversations; it only retains “surprising” information — the orienting response from cognitive science
• Avoiding learned helplessness: The system records both successes and failures, not just errors — preventing the AI from becoming overly cautious
• Progressive trust: New users start with restricted permissions that build up gradually — mirroring trust-building in human social interactions

Visual Entry Points

Evidence System

Primary Evidence Sources

Project Structure Diagram

    flowchart LR
  Package["claudecode/package<br/>v2.1.88"]
  Package --> Pkg["package.json<br/>release boundary"]
  Package --> Readme["README.md<br/>product positioning"]
  Package --> Map["cli.js.map<br/>1,902 source paths"]
  Package --> Schema["sdk-tools.d.ts<br/>tool contracts"]
  Package --> Vendor["vendor/<br/>ripgrep + audio-capture"]
  Map --> Entry["src/entrypoints + src/cli<br/>entry routing"]
  Map --> Tools["src/tools<br/>43 tool entities"]
  Map --> Commands["src/commands<br/>97 command entries"]
  Map --> Services["src/services<br/>service orchestration"]
  Map --> UI["src/components + src/ink<br/>terminal UI"]
  Map --> Memory["src/memdir + SessionMemory<br/>memory and compression"]
  Map --> Ext["src/skills + src/bridge<br/>extension fabric"]
  

Further Reading

• Claude Code Overview
• Visual Map