Analyze Claude Code

Deep dive into Claude Code CLI source code to understand its architecture and implementation.

Setup: Download and Format Source

# One-liner: download, extract, and format
curl -sL "$(curl -s https://registry.npmjs.org/@anthropic-ai/claude-code/latest | jq -r '.dist.tarball')" -o claude-code.tgz && tar -xzf claude-code.tgz && npx js-beautify --replace package/cli.js

Official Documentation

Access official docs via WebFetch tool:

Use the WebFetch tool to query Claude Code's official documentation when you need authoritative information about features, API, or best practices.

Documentation entry point:

• URL: https://code.claude.com/docs/llms.txt
• Contains: Quickstart, CLI Reference, Settings, Hooks, MCP, Skills, Plugins, Security, and more

Example queries:

# Get documentation overview
Use WebFetch tool with:
  url: https://code.claude.com/docs/llms.txt
  prompt: "Show me the table of contents and main sections"

# Query specific topics
Use WebFetch tool with:
  url: https://code.claude.com/docs/llms.txt
  prompt: "How do hooks work? Explain with examples"

Use WebFetch tool with:
  url: https://code.claude.com/docs/llms.txt
  prompt: "What are the available MCP transport types and their differences?"

When to use:

• Verify implementation details not clear from source code
• Understand intended behavior and design philosophy
• Check for recent updates or documentation changes
• Find usage examples and best practices
• Cross-reference source code with official documentation

---

Key Modules

1. Prompts

System prompts that define Claude's behavior and capabilities.

Quick extraction:

# Find Claude identity
grep -n "You are Claude" package/cli.js

# Find prompt sections (around line 435350)
grep -n "# Tone and style\|# Doing tasks\|# Tool usage policy" package/cli.js

# Find tool descriptions
grep -n "Executes a given bash command\|Reads a file from\|Fast file pattern" package/cli.js

Key locations:

• l10 variable: Base identity "You are Claude Code..."
• rc function: Main system prompt builder
• Tool descriptions as template strings (e.g., SEB for Read, c10 for Glob)

Prompt sections: Tone/style, Professional objectivity, Task management, Tool usage policy, Code references

---

Advanced Prompt Discovery

Core Principle: Trace prompts from function entry points using code structure, not content keywords.

Three-Layer Abstraction:

• Layer 3 (Code): Long strings, template vars, API calls (most stable, start here)
• Layer 2 (Structure): Imperative patterns, examples, lists (medium abstraction)
• Layer 1 (Content): Specific text keywords (fragile, avoid dependency)

Tracing Flow:

/command → Command registry → Handler function → Prompt construction

Key search patterns:

# Layer 3: Code characteristics (start here)
grep -n "return \`" package/cli.js           # Template strings
grep -n "messages\s*:\|system\s*:" package/cli.js  # API calls
awk '/return `/{start=NR} /^`/&&NR-start>15{print "Line",start}' package/cli.js  # Long strings

# Layer 2: Structure characteristics
grep -n "You are\|Your task\|Please" package/cli.js  # Imperative patterns
grep -n "<example>" package/cli.js           # Example blocks
grep -n "format.*response\|output.*should" package/cli.js  # Format descriptions

# Combined: Long strings with imperative content
grep -n "return \`" package/cli.js | while read l; do
    line=$(echo $l | cut -d: -f1)
    sed -n "$line,$((line+20))p" package/cli.js | grep -q "You are\|Your task" && echo "Line $line"
done

Tracing workflow (from command):

# 1. Find command definition
grep -n 'name.*"compact"' package/cli.js
# → Line 12345

# 2. Extract command object (check type: "prompt" or "local")
sed -n '12340,12370p' package/cli.js
# → type: "local", handler: (args) => kv1(args)

# 3. Find handler function
grep -n 'function kv1\|const kv1' package/cli.js
# → Line 45678

# 4. Search for prompt construction in handler
sed -n '45678,45900p' package/cli.js | grep -n 'return `\|messages:\|system:'
# → Line 23: return `Your task is to create...

# 5. Extract full prompt
sed -n '45700,46200p' package/cli.js

Prompt identification heuristics:

A code block is likely a prompt if it scores ≥4:

• Contains "You are|Your task|Please|Analyze" (+3)
• Contains "format|structure|output|response" (+2)
• Contains <example> or Example: (+2)
• Contains lists (^[0-9].|^-) with 3+ items (+1)
• Has 3+ paragraphs (blank lines) (+1)

Example: Trace any local command

COMMAND="init"  # or any command name

# Step 1-2: Find command and handler
HANDLER=$(sed -n "$(grep -n "name.*\"$COMMAND\"" package/cli.js | cut -d: -f1),+30p" package/cli.js | \
          grep -o 'handler.*[a-zA-Z_][a-zA-Z0-9_]*' | tail -1)

# Step 3: Find handler line
HANDLER_LINE=$(grep -n "function $HANDLER\|const $HANDLER" package/cli.js | cut -d: -f1)

# Step 4-5: Extract prompts
sed -n "$HANDLER_LINE,$((HANDLER_LINE+300))p" package/cli.js | grep -B2 -A20 'return `'

---

2. Tools

Built-in tools: Bash, Read, Write, Edit, Glob, Grep, Task, WebFetch, etc.

Search patterns:

grep -n "tool.*schema\|toolName\|Tool.*definition" package/cli.js

Key aspects:

• JSON Schema definitions for parameters
• Validation logic
• Execution sandboxing (macOS sandbox-exec, Docker)
• Result handling and token limits

---

3. Subagents

Specialized agents for task delegation: Explore, Plan, General-purpose, Bash, etc.

Search patterns:

grep -n "subagent\|agentType\|Task.*agent" package/cli.js

Key aspects:

• Agent types: Explore (Haiku, read-only), Plan (inherit model), General-purpose (full tools)
• Context isolation (fork mode)
• Permission inheritance
• Background vs foreground execution

---

4. Hooks

Event-driven extensibility mechanism.

Search patterns:

grep -n "registeredHooks\|PreToolUse\|PostToolUse\|hookEvent" package/cli.js

Hook events:

Event	Trigger	Matcher Support
PreToolUse	Before tool execution	Yes
PostToolUse	After tool success	Yes
UserPromptSubmit	User sends prompt	No
SessionStart	Session begins	Yes
Stop	Agent completes	No

Key aspects:

• Exit codes: 0=success, 2=blocking error
• JSON output for decisions (allow/deny/ask)
• updatedInput to modify tool parameters

---

5. Skills

Modular knowledge packages (SKILL.md files).

Search patterns:

grep -n "SKILL\.md\|skill.*description\|loadSkill" package/cli.js

Key aspects:

• Discovery: Only name/description loaded initially
• Activation: Full content loaded when triggered
• Frontmatter: name, description, allowed-tools, model, context, hooks
• Locations: ~/.claude/skills/, .claude/skills/, plugin bundles

---

6. Plugins

Extension packages containing skills, commands, MCP servers.

Search patterns:

grep -n "plugin\.json\|loadPlugin\|pluginRoot" package/cli.js

Structure:

plugin/
├── .claude-plugin/plugin.json  # Metadata
├── commands/                   # Slash commands
├── agents/                     # Custom subagents
├── skills/                     # Skills
├── hooks/hooks.json            # Hook configs
└── .mcp.json                   # MCP servers

Key aspects:

• Namespace isolation (/plugin-name:command)
• Resource isolation for hooks
• Installation via marketplace or --plugin-dir

---

7. Slash Commands

User-invoked commands with / prefix.

Search patterns:

grep -n "slashCommand\|commands/.*\.md\|ARGUMENTS" package/cli.js

Types:

• Built-in: /clear, /compact, /config, /model, etc.
• Custom: .claude/commands/*.md
• Plugin: /plugin:command
• MCP: /mcp__server__prompt

Frontmatter: allowed-tools, description, model, context, hooks

---

8. MCP (Model Context Protocol)

External tool integration via MCP servers.

Search patterns:

grep -n "MCP\|mcpServer\|mcp__" package/cli.js

Key aspects:

• Transport: HTTP (recommended), SSE, stdio
• Scopes: local, project, user
• Tool format: mcp__<server>__<tool>
• Dynamic tool discovery via list_changed

---

9. Memory (CLAUDE.md)

Persistent instructions loaded into context.

Search patterns:

grep -n "CLAUDE\.md\|loadMemory\|rules/.*\.md" package/cli.js

Hierarchy (high to low priority):

1. Enterprise: /Library/Application Support/ClaudeCode/CLAUDE.md
2. Project: ./CLAUDE.md or ./.claude/CLAUDE.md
3. Rules: ./.claude/rules/*.md
4. User: ~/.claude/CLAUDE.md
5. Local: ./CLAUDE.local.md

---

10. Settings

Configuration with four-level scope system.

Search patterns:

grep -n "settings\.json\|loadSettings\|settingsScope" package/cli.js

Priority (high to low):

1. Managed: System-level, IT-deployed
2. CLI args: Temporary session override
3. Local: .claude/settings.local.json
4. Project: .claude/settings.json
5. User: ~/.claude/settings.json

Key configs: permissions, hooks, model, env, sandbox

---

Analysis Tips

Search tools - Examples use grep, but any search tool works:

• grep -n "pattern" file - Basic search
• rg -n "pattern" file - Ripgrep (faster)
• ag "pattern" file - The Silver Searcher
• Use Claude Code's built-in Grep tool for best integration

View context - After finding line numbers:

• sed -n 'START,ENDp' file - Extract line range
• rg -A5 -B5 "pattern" file - Show context around matches

Key principles:

1. Variable names are minified - Search for string literals, not variable names
2. Template strings - Many prompts use backtick templates with ${}
3. Adjacent code - Functions are often defined near their string constants
4. Follow the strings - Start from user-visible text to trace implementation