Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
801 lines (629 loc) · 35.6 KB

DOCUMENTATION.md

File metadata and controls

801 lines (629 loc) · 35.6 KB

English | 中文

Claude Code — Source Code Documentation & Analysis

Claude Code is Anthropic's official CLI for Claude. This document provides a comprehensive reverse-engineering analysis of its source code architecture, modules, and internal design patterns.

How to Read This Document

This document is the result of a deep-dive analysis into the Claude Code source tree. It is intended for developers and engineers who want to understand how Claude Code works under the hood — its architecture, module boundaries, data flow, and design decisions.

Structure: The document is organized top-down, starting with the project overview and technology stack, then drilling into each major subsystem (tools, commands, state, services, UI). Each section is self-contained; you can jump to any section via the Table of Contents.

Audience: Intermediate-to-advanced developers familiar with TypeScript, React, and CLI tooling. Prior experience with AI/LLM tooling is helpful but not required.

Scope: This covers the source tree structure, module inventory, and architectural patterns. It does not cover runtime behavior in depth, nor does it include performance benchmarks or security audits.

Table of Contents

  1. Project Overview
  2. Technology Stack
  3. Directory Structure
  4. Entry Points
  5. Core Architecture
  6. Tool System
  7. Command System
  8. State Management
  9. Task System
  10. Services & Integrations
  11. UI Layer
  12. Utilities
  13. Special Modes
  14. Plugins & Skills
  15. Hooks & Extensibility
  16. File Statistics
  17. Architectural Patterns

1. Project Overview

Claude Code is a feature-rich, interactive terminal application that enables AI-assisted software engineering directly from the command line. It provides:

  • Interactive REPL for conversing with Claude about code
  • 40+ tools for file operations, shell execution, web search, and more
  • 100+ slash commands for workflows like committing, reviewing, debugging
  • Agent/task system for parallelizing complex work across sub-agents
  • Plan mode for designing implementation strategies before coding
  • MCP (Model Context Protocol) integration for extensible server-side tools
  • Plugin & skill system for user-defined extensions
  • Voice mode, desktop/mobile bridges, and remote sessions

2. Technology Stack

Layer Technology
Language TypeScript (.ts / .tsx)
Runtime Bun (bundler, feature flags via bun:bundle)
UI Framework React + Ink (terminal React renderer)
API Client @anthropic-ai/sdk (Anthropic SDK)
MCP @modelcontextprotocol/sdk
CLI Framework @commander-js/extra-typings
Validation Zod v4
Styling Chalk (terminal colors)
State Zustand-style store + React Context

3. Directory Structure

claude-code-analysis/
└── src/                          # All source code (single top-level directory)
    ├── main.tsx                  # Primary bootstrap & initialization
    ├── QueryEngine.ts            # Conversation loop orchestrator
    ├── Tool.ts                   # Tool type definitions & interfaces
    ├── Task.ts                   # Task type definitions & lifecycle
    ├── commands.ts               # Command registry
    ├── tools.ts                  # Tool registry & factory
    ├── context.ts                # System/user context builder
    ├── query.ts                  # Query context preparation
    ├── setup.ts                  # Setup phase orchestration
    ├── history.ts                # Chat session history
    ├── cost-tracker.ts           # Token usage & pricing
    ├── ink.ts                    # Ink rendering wrapper
    ├── replLauncher.tsx          # REPL React component launcher
    ├── tasks.ts                  # Task execution manager
    │
    ├── commands/                 # 101 command modules (slash commands)
    ├── tools/                    # 41 tool implementations
    ├── services/                 # Core services (API, MCP, analytics, etc.)
    ├── components/               # React/Ink UI components (130+ files)
    ├── utils/                    # Utility functions (300+ files)
    ├── state/                    # Application state management
    ├── types/                    # TypeScript type definitions
    ├── hooks/                    # React hooks
    ├── schemas/                  # Zod validation schemas
    ├── tasks/                    # Task type implementations
    ├── entrypoints/              # Entry point definitions (CLI, SDK, MCP)
    ├── bootstrap/                # Application startup & global state
    ├── screens/                  # Full-screen UI layouts
    ├── plugins/                  # Plugin system (bundled plugins)
    ├── skills/                   # Custom skill system (bundled skills)
    ├── memdir/                   # Memory directory auto-discovery
    ├── constants/                # Application constants
    ├── migrations/               # Data/schema migrations
    ├── ink/                      # Ink terminal customizations
    ├── keybindings/              # Keyboard binding system
    ├── context/                  # React contexts (mailbox, notifications)
    ├── query/                    # Query processing modules
    ├── outputStyles/             # Output formatting styles
    ├── vim/                      # Vim mode integration
    ├── voice/                    # Voice input/output
    ├── native-ts/                # Native TypeScript bindings
    ├── assistant/                # Kairos (assistant) mode
    ├── bridge/                   # Bridge mode (always-on remote)
    ├── buddy/                    # Buddy/teammate system
    ├── coordinator/              # Multi-agent coordination
    ├── remote/                   # Remote session handling
    ├── server/                   # Server implementation
    ├── cli/                      # CLI argument parsing
    └── upstreamproxy/            # Upstream proxy setup

4. Entry Points

Primary Entry: src/main.tsx

The main bootstrap file (~1,400 lines). Performs:

  1. Startup profiling via startupProfiler.ts
  2. MDM (Mobile Device Management) raw read prefetch
  3. Keychain prefetch (macOS OAuth + API key reads in parallel)
  4. Feature flag initialization via Bun's feature() for dead code elimination
  5. CLI argument parsing via Commander.js
  6. Authentication (API key, OAuth, AWS Bedrock, GCP Vertex, Azure)
  7. GrowthBook initialization (A/B testing & feature flags)
  8. Policy limits and remote managed settings loading
  9. Tool, command, skill, and MCP server registration
  10. REPL launch via replLauncher.tsx

Other Entry Points (src/entrypoints/)

File Purpose
cli.tsx CLI entry point with React/Ink UI rendering
init.ts Bootstrap initialization, version checks
mcp.ts Model Context Protocol integration
agentSdkTypes.ts Type definitions for the Agent SDK
sandboxTypes.ts Sandbox execution environment types
sdk/ SDK-related implementations

Setup Phase: src/setup.ts

Orchestrates:

  • Node.js version validation
  • Worktree initialization
  • Session & permission mode setup
  • Git root detection
  • UDS messaging server startup

5. Core Architecture

5.1 Query Engine (src/QueryEngine.ts)

The heart of the application (~46KB). Manages the conversation loop between user and Claude:

  • Message management — maintains conversation history with user, assistant, system, and tool messages
  • Streaming — real-time token streaming with tool use execution
  • Auto-compaction — automatically compresses context when approaching window limits
  • Prompt caching — optimizes repeated context through cache-aware strategies
  • Retry logic — handles API errors, rate limits, and overload with backoff
  • Usage tracking — counts tokens (input/output/cache read/write) and costs
  • Tool orchestration — dispatches tool calls, collects results, manages permissions

5.2 Context Builder (src/context.ts, src/query.ts)

Prepares the system prompt and user context:

  • Discovers and merges CLAUDE.md files (project, user, global)
  • Builds system context (OS, shell, platform, git status)
  • Integrates user context (permissions, working directories)
  • Caches context for performance across queries

5.3 Cost Tracking (src/cost-tracker.ts)

Tracks per-session costs:

  • Token counting by model (input, output, cache read/write)
  • USD cost calculation via pricing tables
  • Session duration tracking
  • Web search request counting
  • File change metrics

6. Tool System

Architecture (src/Tool.ts, src/tools.ts)

Each tool is a self-contained module with:

  • JSON Schema input validation
  • Permission model (ask/allow/deny modes)
  • Progress tracking types
  • Error handling and user prompting

Complete Tool Inventory (41 tools)

File Operations

Tool Purpose
FileReadTool Read file contents with line ranges
FileWriteTool Create or overwrite files
FileEditTool Exact string replacement edits
GlobTool Pattern-based file matching
GrepTool Content search with regex (ripgrep-based)

Code Execution

Tool Purpose
BashTool Execute shell commands with timeout
PowerShellTool Execute PowerShell commands (Windows)
REPLTool Execute Python code (internal only)
NotebookEditTool Jupyter notebook cell operations

Web & Search

Tool Purpose
WebFetchTool Fetch and parse web content
WebSearchTool Search the internet
ToolSearchTool Search available deferred tools

Agent & Task Management

Tool Purpose
AgentTool Spawn sub-agents for parallel work
TaskCreateTool Create new background tasks
TaskGetTool Retrieve task status and results
TaskUpdateTool Update task status or description
TaskListTool List all tasks and their states
TaskStopTool Kill a running task
TaskOutputTool Stream/read task output
SendMessageTool Send messages to running agents

Planning & Workflow

Tool Purpose
EnterPlanModeTool Enter read-only planning mode
ExitPlanModeTool Exit planning mode with approval
EnterWorktreeTool Create isolated git worktree
ExitWorktreeTool Return from worktree with changes

MCP (Model Context Protocol)

Tool Purpose
MCPTool Call tools on MCP servers
McpAuthTool Authenticate with MCP servers
ListMcpResourcesTool List MCP server resources
ReadMcpResourceTool Read specific MCP resources

Configuration & System

Tool Purpose
ConfigTool Read/modify settings
SkillTool Execute user-defined skills
AskUserQuestionTool Prompt user for input/clarification
BriefTool Generate session briefs
TodoWriteTool Manage todo lists
SleepTool Pause execution for a duration

Team & Remote

Tool Purpose
TeamCreateTool Create agent teams
TeamDeleteTool Delete agent teams
RemoteTriggerTool Trigger remote task execution
ScheduleCronTool Schedule recurring tasks
LSPTool Language Server Protocol integration

Internal

Tool Purpose
SyntheticOutputTool Synthetic output for structured responses

7. Command System

Registry (src/commands.ts)

Commands are modular directories under src/commands/, each containing an index.ts (or similar) that exports a Command definition with name, description, handler, and optional aliases.

Complete Command Inventory (101 modules)

Git & Version Control

commit, commit-push-pr, diff, branch, review, autofix-pr, pr_comments, teleport, rewind, tag

Session & History

session, resume, clear, compact, export, share, summary, context

Configuration & Settings

config, permissions, privacy-settings, theme, color, keybindings, vim, output-style, statusline, env

Agent & Task Management

agents, tasks, brief

File & Code Operations

files, add-dir, diff, debug-tool-call, copy

Development & Debugging

doctor, heapdump, perf-issue, stats, bughunter, ctx_viz, ant-trace

Authentication

login, logout, oauth-refresh

Extensions & Plugins

mcp, plugin, reload-plugins, skills

Workspace

plan, sandbox-toggle, init

Information & Help

help, version, cost, usage, extra-usage, release-notes, status, insights

Platform Integration

desktop, mobile, chrome, ide, install, install-github-app, install-slack-app

Memory & Knowledge

memory, good-claude

Model & Performance

model, effort, fast, thinkback, thinkback-play, advisor

Special Operations

bridge, voice, remote-setup, remote-env, stickers, feedback, onboarding, passes, ultraplan, rename, exit

8. State Management

Store Architecture (src/state/)

File Purpose
AppState.tsx React Context provider with useAppState(selector) hook
AppStateStore.ts Central state shape definition
store.ts Zustand-style store implementation

Key State Fields

{
  settings: UserSettings           // User configuration from settings.json
  mainLoopModel: string            // Active Claude model
  messages: Message[]              // Conversation history
  tasks: TaskState[]               // Running/completed tasks
  toolPermissionContext: {         // Permission rules per tool
    rules: PermissionRule[]
    bypassMode: 'auto' | 'block' | 'ask'
    denialTracking: DenialTrackingState
  }
  kairosEnabled: boolean           // Assistant mode flag
  remoteConnectionStatus: Status   // Remote session connectivity
  replBridgeEnabled: boolean       // Always-on bridge (CCR) state
  speculationState: Cache          // Inline speculation cache/preview
}

9. Task System

Task Types (src/Task.ts)

Type Description
local_bash Local shell command execution
local_agent Local sub-agent (spawned via AgentTool)
remote_agent Remote agent execution
in_process_teammate In-process teammate (shared memory space)
local_workflow Local multi-step workflow
monitor_mcp MCP server monitoring task
dream Auto-dream background task

Task Lifecycle

pending -> running -> completed
                   -> failed
                   -> killed

Task State Shape

{
  id: string           // Unique ID with type prefix (e.g., "b-xxx" for bash)
  type: TaskType
  status: TaskStatus
  description: string
  startTime: number
  endTime?: number
  outputFile: string   // Disk-persisted output
  outputOffset: number // Current read position
  notified: boolean    // Whether completion was reported
}

10. Services & Integrations

10.1 API Client (src/services/api/)

File Purpose
client.ts Anthropic SDK client with multi-provider support
claude.ts Message streaming & tool use handling
bootstrap.ts Bootstrap data fetching on startup
usage.ts Token usage recording
errors.ts / errorUtils.ts Error classification and handling
logging.ts API request/response logging
withRetry.ts Exponential backoff retry logic
filesApi.ts File upload/download
sessionIngress.ts Remote session bridging
grove.ts Grove integration
referral.ts Referral/passes system

Supported Providers:

  • Anthropic Direct API
  • AWS Bedrock
  • Google Cloud Vertex AI
  • Azure Foundry

10.2 MCP Integration (src/services/mcp/)

File Purpose
client.ts MCP client implementation
types.ts Server definitions & connection types
config.ts Configuration loading & validation
auth.ts OAuth/authentication for MCP servers
officialRegistry.ts Official MCP server registry
InProcessTransport.ts In-process MCP transport
normalization.ts URL/config normalization
elicitationHandler.ts User prompting via MCP

10.3 Analytics & Telemetry (src/services/analytics/)

File Purpose
index.ts Event logging API
growthbook.ts Feature flagging & A/B testing
sink.ts Analytics sink configuration
datadog.ts Datadog integration
firstPartyEventLogger.ts First-party analytics
metadata.ts Event metadata enrichment

10.4 Context Compaction (src/services/compact/)

File Purpose
compact.ts Full context window compaction
autoCompact.ts Automatic compaction triggers
microCompact.ts Selective message pruning
compactWarning.ts User warnings about compaction
sessionMemoryCompact.ts Memory persistence across compaction

10.5 Other Services

Directory/File Purpose
SessionMemory/ Session memory persistence & transcripts
MagicDocs/ Intelligent documentation generation
AgentSummary/ Agent execution summaries
PromptSuggestion/ Suggested follow-up prompts
extractMemories/ Learning extraction from conversations
plugins/ Plugin lifecycle management
oauth/ OAuth client flows
lsp/ Language Server Protocol client
remoteManagedSettings/ Remote configuration sync
settingsSync/ Settings synchronization
teamMemorySync/ Team memory synchronization
policyLimits/ Rate limiting & quotas
autoDream/ Auto-dream background features
tips/ Contextual tips system
toolUseSummary/ Tool usage analytics
voice.ts / voiceStreamSTT.ts Voice input handling

11. UI Layer

Framework

The UI is built with React rendered to the terminal via Ink. Components use standard React patterns (hooks, context, props) but render to terminal ANSI output instead of DOM.

Core Application Components

Component File Purpose
App components/App.tsx Root application component
REPL screens/REPL.tsx Main REPL screen
Messages components/Messages.tsx Conversation message list
PromptInput components/PromptInput/ User input with autocomplete
StatusLine components/StatusLine.tsx Bottom status bar

Component Categories

Message Display

Message.tsx, MessageRow.tsx, MessageResponse.tsx, MessageModel.tsx, MessageTimestamp.tsx, MessageSelector.tsx, messages/ (subdirectory for specialized message types)

Dialog & Modal Components

TrustDialog/, AutoModeOptInDialog.tsx, BypassPermissionsModeDialog.tsx, CostThresholdDialog.tsx, BridgeDialog.tsx, ExportDialog.tsx, InvalidConfigDialog.tsx, InvalidSettingsDialog.tsx, ManagedSettingsSecurityDialog/, IdeAutoConnectDialog.tsx, IdleReturnDialog.tsx, WorktreeExitDialog.tsx, RemoteEnvironmentDialog.tsx

Code Display

HighlightedCode/, StructuredDiff/, FileEditToolDiff.tsx

Settings & Configuration

Settings/, ThemePicker.tsx, OutputStylePicker.tsx, ModelPicker.tsx, LanguagePicker.tsx

Task & Agent UI

tasks/, teams/, agents/, CoordinatorAgentStatus.tsx, TaskListV2.tsx, TeammateViewHeader.tsx

Navigation & Search

GlobalSearchDialog.tsx, HistorySearchDialog.tsx, QuickOpenDialog.tsx, SearchBox.tsx

Design System

design-system/, Spinner/, CustomSelect/, LogoV2/, HelpV2/

Permissions

permissions/ (role-based access dialogs and prompts)

12. Utilities

The src/utils/ directory contains 300+ files providing low-level functionality. Key categories:

Git & Version Control

File/Dir Purpose
git.ts Git command wrappers
git/ Extended git utilities
gitDiff.ts Diff generation and parsing
gitSettings.ts Git instruction toggles
github/ GitHub API helpers
worktree.ts Git worktree automation

Shell & Process

File/Dir Purpose
Shell.ts Shell execution wrapper
shell/ Shell configuration and helpers
bash/ Bash-specific utilities
powershell/ PowerShell utilities
execFileNoThrow.ts Safe process spawning
process.ts Process management

Authentication & Security

File/Dir Purpose
auth.ts API key, OAuth, AWS/GCP credential management
secureStorage/ Keychain integration (macOS)
permissions/ Permission rules, filesystem sandboxing
crypto.ts Cryptographic utilities
sandbox/ Sandbox environment

Configuration

File/Dir Purpose
config.ts .claude/config.json management
settings/ settings.json validation & application
env.ts Static environment variables
envDynamic.ts Dynamic environment detection
envUtils.ts Environment variable parsing
managedEnv.ts Managed environment configuration

File System

File/Dir Purpose
claudemd.ts CLAUDE.md auto-discovery and parsing
fileStateCache.ts File change tracking
fileHistory.ts File snapshots for undo
filePersistence/ Persistent file storage
glob.ts Glob pattern matching
ripgrep.ts Ripgrep integration

AI & Model

File/Dir Purpose
model/ Model selection & context window management
modelCost.ts Token pricing tables
thinking.ts Extended thinking mode configuration
effort.ts Task effort level management
fastMode.ts Speed optimization mode
advisor.ts AI advisor integration
tokens.ts Token counting and estimation

Agent & Swarm

File/Dir Purpose
swarm/ Multi-agent swarm coordination
teammate.ts Teammate/agent mode utilities
forkedAgent.ts Forked agent process management
agentContext.ts Agent execution context

Performance & Diagnostics

File/Dir Purpose
startupProfiler.ts Startup performance monitoring
headlessProfiler.ts Runtime profiling
fpsTracker.ts Frame rate metrics
diagLogs.ts Diagnostic logging (PII-free)
debug.ts Debug utilities

UI Helpers

File/Dir Purpose
theme.ts Theme management
renderOptions.ts Ink rendering configuration
format.ts Number/duration formatting
markdown.ts Markdown processing
cliHighlight.ts Syntax highlighting for CLI

13. Special Modes

13.1 Bridge Mode (src/bridge/)

Always-on connection to Claude.ai via WebSocket-based session ingress. Enables persistent background sessions and remote access.

13.2 Kairos / Assistant Mode (src/assistant/)

Enterprise assistant features:

  • Background task handling
  • Push notifications
  • GitHub webhook subscriptions
  • Remote task monitoring
  • Feature-gated via KAIROS flag

13.3 Coordinator Mode (src/coordinator/)

Multi-agent orchestration:

  • Task panel management
  • Agent interaction coordination
  • Feature-gated via COORDINATOR_MODE flag

13.4 Voice Mode (src/voice/)

Voice input/output support:

  • Speech-to-Text (STT) integration
  • Text-to-speech
  • Voice transcription
  • Voice keyterms detection

13.5 Plan Mode

Read-only mode for designing implementation strategies:

  • Creates plan files in .claude/plans/
  • Restricts tools to read-only operations
  • Requires explicit user approval before execution
  • Managed by EnterPlanModeTool / ExitPlanModeTool

13.6 Worktree Mode

Git worktree isolation for safe experimentation:

  • Creates temporary git worktrees
  • Supports tmux session management
  • Temporary branch creation
  • Changes can be merged or discarded

13.7 Vim Mode (src/vim/)

Vim keybinding integration for the terminal input.

14. Plugins & Skills

Plugin System (src/plugins/)

  • Bundled plugins in plugins/bundled/ (keyboard shortcuts, themes, etc.)
  • Plugin lifecycle management via PluginInstallationManager
  • CLI commands for plugin management
  • Hot-reload support via reload-plugins command

Skill System (src/skills/)

  • Bundled skills in skills/bundled/ (commit, review, simplify, etc.)
  • Skills are named prompts that can be invoked via /skill-name
  • Skill discovery and execution engine
  • Change detection for live updates

15. Hooks & Extensibility

Hook Schema (src/schemas/hooks.ts)

Defined via Zod validation:

  • HookEvent — pre-/post-execution lifecycle hooks
  • PromptRequest / PromptResponse — user prompting protocol
  • Sync and async hook response schemas
  • Permission decision hooks

React Hooks (src/hooks/)

Hook Purpose
useSettings Settings change detection
useTerminalSize Terminal dimension tracking
useExitOnCtrlC Signal handling
useBlink Cursor blinking animation
useDoublePress Double-keypress detection
useCanUseTool Tool permission validation

Utility Hooks (src/utils/hooks/)

Additional hooks for shell config, permission state, and tool behavior.

16. File Statistics

Category Count
Total TypeScript files 1,884
Command modules 101
Tool implementations 41
UI components 130+
Utility files 300+
Service modules 35+
Top-level source files 18
Entry points 6
Subdirectories in src/ 37

17. Architectural Patterns

Lazy Loading & Dead Code Elimination

Conditional imports via require() gated by Bun's feature() flags. This enables tree-shaking of entire subsystems (e.g., KAIROS, COORDINATOR_MODE) at bundle time.

const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js')
  : null;

Tool-Based Execution Model

Every interaction with the external world goes through a registered Tool. Tools have:

  • Declarative JSON Schema inputs
  • Permission checks before execution
  • Progress reporting during execution
  • Structured result output

Command Pattern

Slash commands are modular directories, each exporting a Command object. The registry in commands.ts aggregates them with optional feature-gate conditions.

Message-Driven Architecture

The conversation is a sequence of typed messages (UserMessage, AssistantMessage, SystemMessage, ProgressMessage, etc.) managed by the QueryEngine. Tool results are injected as ToolResultBlockParam messages.

Context Compaction

When conversation context approaches the model's window limit, the system automatically compacts older messages while preserving essential context. Multiple strategies are available: full compaction, micro-compaction (selective pruning), and session memory persistence.

Permission-First Security

Every tool execution passes through a permission check. Modes include:

  • Ask — prompt user for each action
  • Auto-allow — allow with trust rules
  • Deny — block specific operations
  • Filesystem sandboxing — restrict file access to project directories

React Terminal UI

The entire UI is a React component tree rendered via Ink. This enables:

  • Declarative UI updates
  • Component composition and reuse
  • State-driven rendering
  • Hooks for terminal-specific behaviors (cursor, resize, keyboard)

Contributing

Contributions are welcome! If you've discovered additional architectural details, found inaccuracies, or want to expand coverage of a specific subsystem:

  1. Fork this repository
  2. Create a branch for your changes (git checkout -b fix/tool-system-details)
  3. Submit a pull request with a clear description of what you added or corrected

Please keep contributions factual and technically precise. This is a reference document — speculation should be clearly marked as such.

Disclaimer: This is an unofficial, independent analysis. Claude Code is a product of Anthropic. All trademarks belong to their respective owners.

Generated on 2025-03-31. Based on analysis of the Claude Code source tree.