Skip to content

exploration-guide.md

Latest commit

 

History

History
246 lines (174 loc) · 6.68 KB

exploration-guide.md

File metadata and controls

246 lines (174 loc) · 6.68 KB

Exploration Guide

How to navigate and study the Claude Code source code.

Quick Start

This is a read-only reference codebase — there's no build system or test suite. The goal is to understand how a production AI coding assistant is built.

Orientation

What Where
CLI entrypoint src/main.tsx
Core LLM engine src/QueryEngine.ts (~46K lines)
Tool definitions src/Tool.ts (~29K lines)
Command registry src/commands.ts (~25K lines)
Tool registry src/tools.ts
Context collection src/context.ts
All tool implementations src/tools/ (40 subdirectories)
All command implementations src/commands/ (~85 subdirectories + 15 files)

Finding Things

"How does tool X work?"

  1. Go to src/tools/{ToolName}/
  2. Main implementation is {ToolName}.ts or .tsx
  3. UI rendering is in UI.tsx
  4. System prompt contribution is in prompt.ts

Example — understanding BashTool:

src/tools/BashTool/
├── BashTool.ts      ← Core execution logic
├── UI.tsx           ← How bash output renders in terminal
├── prompt.ts        ← What the system prompt says about bash
└── ...

"How does command X work?"

  1. Check src/commands/{command-name}/ (directory) or src/commands/{command-name}.ts (file)
  2. Look for the getPromptForCommand() function (PromptCommands) or direct implementation (LocalCommands)

"How does feature X work?"

Feature Start Here
Permissions src/hooks/toolPermission/
IDE bridge src/bridge/bridgeMain.ts
MCP client src/services/mcp/
Plugin system src/plugins/ + src/services/plugins/
Skills src/skills/
Voice input src/voice/ + src/services/voice.ts
Multi-agent src/coordinator/
Memory src/memdir/
Authentication src/services/oauth/
Config schemas src/schemas/
State management src/state/

"How does an API call flow?"

Trace from user input to API response:

src/main.tsx                    ← CLI parsing
  → src/replLauncher.tsx        ← REPL session start
    → src/QueryEngine.ts        ← Core engine
      → src/services/api/       ← Anthropic SDK client
        → (Anthropic API)       ← HTTP/streaming
      ← Tool use response
      → src/tools/{ToolName}/   ← Tool execution
      ← Tool result
      → (feed back to API)      ← Continue the loop

Code Patterns to Recognize

buildTool() — Tool Factory

Every tool uses this pattern:

export const MyTool = buildTool({
  name: 'MyTool',
  inputSchema: z.object({ ... }),
  async call(args, context) { ... },
  async checkPermissions(input, context) { ... },
})

Feature Flag Gates

import { feature } from 'bun:bundle'

if (feature('VOICE_MODE')) {
  // This code is stripped at build time if VOICE_MODE is off
}

Anthropic-Internal Gates

if (process.env.USER_TYPE === 'ant') {
  // Anthropic employee-only features
}

Index Re-exports

Most directories have an index.ts that re-exports the public API:

// src/tools/BashTool/index.ts
export { BashTool } from './BashTool.js'

Lazy Dynamic Imports

Heavy modules are loaded only when needed:

const { OpenTelemetry } = await import('./heavy-module.js')

ESM with .js Extensions

Bun convention — all imports use .js extensions even for .ts files:

import { something } from './utils.js'  // Actually imports utils.ts

Key Files by Size

The largest files contain the most logic and are worth studying:

File Lines What's Inside
QueryEngine.ts ~46K Streaming, tool loops, retries, token counting
Tool.ts ~29K Tool types, buildTool, permission models
commands.ts ~25K Command registry, conditional loading
main.tsx — CLI parser, startup optimization
context.ts — OS, shell, git, user context assembly

Study Paths

Path 1: "How does a tool work end-to-end?"

  1. Read src/Tool.ts — understand the buildTool interface
  2. Pick a simple tool like FileReadTool in src/tools/FileReadTool/
  3. Trace how QueryEngine.ts calls tools during the tool loop
  4. See how permissions are checked in src/hooks/toolPermission/

Path 2: "How does the UI work?"

  1. Read src/screens/REPL.tsx — the main screen
  2. Explore src/components/ — pick a few components
  3. See src/hooks/useTextInput.ts — how user input is captured
  4. Check src/ink/ — the Ink renderer wrapper

Path 3: "How does the IDE integration work?"

  1. Start at src/bridge/bridgeMain.ts
  2. Follow bridgeMessaging.ts for the message protocol
  3. See bridgePermissionCallbacks.ts for how permissions route to the IDE
  4. Check replBridge.ts for REPL session bridging

Path 4: "How do plugins extend Claude Code?"

  1. Read src/types/plugin.ts — the plugin API surface
  2. See src/services/plugins/ — how plugins are loaded
  3. Check src/plugins/builtinPlugins.ts — built-in examples
  4. Look at src/plugins/bundled/ — bundled plugin code

Path 5: "How does MCP work?"

  1. Read src/services/mcp/ — the MCP client
  2. See src/tools/MCPTool/ — how MCP tools are invoked
  3. Check src/entrypoints/mcp.ts — Claude Code as an MCP server
  4. Look at src/skills/mcpSkillBuilders.ts — skills from MCP

Using the MCP Server for Exploration

This repo includes a standalone MCP server (mcp-server/) that lets any MCP-compatible client explore the source code. See the MCP Server README for setup.

Once connected, you can ask an AI assistant to explore the source:

  • "How does the BashTool work?"
  • "Search for where permissions are checked"
  • "List all files in the bridge directory"
  • "Read QueryEngine.ts lines 1-100"

Grep Patterns

Useful grep/ripgrep patterns for finding things:

# Find all tool definitions
rg "buildTool\(" src/tools/

# Find all command definitions
rg "satisfies Command" src/commands/

# Find feature flag usage
rg "feature\(" src/

# Find Anthropic-internal gates
rg "USER_TYPE.*ant" src/

# Find all React hooks
rg "^export function use" src/hooks/

# Find all Zod schemas
rg "z\.object\(" src/schemas/

# Find all system prompt contributions
rg "prompt\(" src/tools/*/prompt.ts

# Find permission rule patterns
rg "checkPermissions" src/tools/

See Also