Claude Code Source Tutorial -- Project Overview & Quick Navigation
Background
Claude Code is Anthropic's CLI tool that lets users interact with Claude from the terminal to perform software engineering tasks: editing files, running commands, searching codebases, and coordinating workflows.
This repository is a source snapshot that became publicly accessible on March 31, 2026, through a source map exposure in the npm distribution. It is maintained for educational and security research purposes only.
Tech Stack
| Category | Technology |
|---|---|
| Runtime | Bun |
| Language | TypeScript (strict) |
| Terminal UI | React + Ink (custom fork) |
| CLI Parsing | Commander.js (extra-typings) |
| Schema Validation | Zod v4 |
| Code Search | ripgrep |
| Protocols | MCP SDK, LSP |
| API | Anthropic SDK |
| Telemetry | OpenTelemetry + gRPC |
| Feature Flags | GrowthBook + bun:bundle compile-time elimination |
| Auth | OAuth 2.0, JWT, macOS Keychain |
Scale
- ~1,900 source files, 512,000+ lines of code
- Single
src/package structure, nopackage.json(this snapshot contains source only) - 301 directories
Quick Navigation
| I want to learn about... | Chapter | Key Files |
|---|---|---|
| Overall architecture | 01-architecture | src/ directory structure |
| How it starts up | 02-startup-flow | entrypoints/cli.tsx, main.tsx |
| How the agent loop works | 03-core-loop | query.ts, QueryEngine.ts |
| How tools are defined and run | 04-tool-system | Tool.ts, tools.ts, services/tools/ |
| How permissions work | 05-permission-security | utils/permissions/, types/permissions.ts |
| How system prompt is assembled | 06-context-prompt | constants/prompts.ts, context.ts |
| How memory works | 07-memory-system | memdir/, services/SessionMemory/ |
| How the terminal UI renders | 08-terminal-ui | ink/, screens/REPL.tsx, components/ |
| MCP integration | 09-mcp-integration | services/mcp/, tools/MCPTool/ |
| Multi-agent coordination | 10-multi-agent | tools/AgentTool/, utils/swarm/ |
| Plugin and skill system | 11-plugin-skill | plugins/, skills/, tools/SkillTool/ |
| API calls and streaming | 12-api-streaming | services/api/claude.ts, services/api/client.ts |
| Configuration system | 13-config-settings | utils/settings/ |
| Context compaction | 14-compact-context-mgmt | services/compact/ |
| Slash command system | 15-command-system | commands.ts, commands/ |
| Design patterns summary | 16-design-patterns | Cross-file |
Recommended Reading Paths
Fast Track (~2 hours)
For readers who want to quickly grasp the core mechanisms:
00-overview -> 01-architecture -> 03-core-loop -> 04-tool-system -> 06-context-prompt
This covers the agent's "brain" -- how the loop runs, how tools execute, and how prompts are assembled.
Full Track (~1-2 days)
For systematic, in-depth study, read all 17 documents in order:
00 -> 01 -> 02 -> 03 -> 04 -> 05 -> 06 -> 07 -> 08 -> 09 -> 10 -> 11 -> 12 -> 13 -> 14 -> 15 -> 16
By Interest
- Agent core: 03 -> 04 -> 05 -> 06
- Extensibility: 09 -> 10 -> 11 -> 15
- Engineering practices: 02 -> 12 -> 13 -> 14 -> 16
- UI implementation: 08
Source Directory Overview
src/
├── main.tsx # Main entry (Commander CLI + Ink rendering)
├── query.ts # Core agent loop
├── QueryEngine.ts # SDK/headless query engine wrapper
├── Tool.ts # Tool type definitions and context
├── tools.ts # Tool registry
├── commands.ts # Command registry
├── context.ts # Context collection (CLAUDE.md, git, etc.)
├── cost-tracker.ts # Token cost tracking
│
├── entrypoints/ # Entry points (cli.tsx, init.ts, mcp.ts)
├── bootstrap/ # Global bootstrap state
├── screens/ # Full-screen UIs (REPL, Doctor)
├── query/ # Query pipeline helpers (deps, config, stopHooks)
│
├── tools/ # ~40 tool implementations
├── commands/ # ~50 slash commands
├── components/ # ~140 Ink UI components
├── hooks/ # React hooks
├── ink/ # Ink rendering engine (custom fork)
├── services/ # External service integrations (API, MCP, OAuth, etc.)
├── utils/ # Utilities (permissions, settings, model, etc.)
│
├── plugins/ # Plugin system
├── skills/ # Skill system
├── bridge/ # IDE bridge
├── memdir/ # Persistent memory directory
├── tasks/ # Task management (sub-agents, teammates)
├── state/ # State management
├── keybindings/ # Keybinding configuration
├── vim/ # Vim mode
├── voice/ # Voice input
├── remote/ # Remote sessions
└── ...
Hands-on Experiments
In addition to reading, we provide 15 Python experiments that let you replicate Claude Code's core design patterns through code.
Experiments support three modes: --mock (offline), --provider anthropic, --provider openai.
Experiment Directory
| Experiment | Chapter | Track |
|---|---|---|
| exp_03 Core Agent Loop | 03 - Core Loop | Core |
| exp_04 Tool System | 04 - Tool System | Core |
| exp_05 Permission Engine | 05 - Permissions | Core |
| exp_06 Prompt Assembly | 06 - Context/Prompt | Core |
| exp_07 Memory System | 07 - Memory | Core |
| exp_09 MCP Client | 09 - MCP | Core |
| exp_10 Multi-Agent | 10 - Multi-Agent | Core |
| exp_12 Streaming API | 12 - API/Streaming | Core |
| exp_14 Context Compaction | 14 - Compaction | Core |
| exp_02 Startup Flow | 02 - Startup Flow | Comprehensive |
| exp_08 Terminal UI | 08 - Terminal UI | Comprehensive |
| exp_11 Plugin/Skill | 11 - Plugin/Skill | Comprehensive |
| exp_13 Config System | 13 - Config | Comprehensive |
| exp_15 Command System | 15 - Commands | Comprehensive |
| exp_16 Design Patterns | 16 - Patterns | Comprehensive |
See the Experiment Guide for full setup instructions.
Next
Go to 01-architecture.md to understand the overall architecture.