Exploring the source

This is a read-only reference codebase — there is no build system or test suite to run. 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?

Every tool lives under src/tools/{ToolName}/ and follows a consistent internal layout:

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
└── ...

Go to src/tools/{ToolName}/
Open {ToolName}.ts or {ToolName}.tsx for the main implementation
Open UI.tsx for terminal rendering
Open prompt.ts for the system prompt contribution

How does command X work?

Check src/commands/{command-name}/ (directory) or src/commands/{command-name}.ts (file)
Look for getPromptForCommand() for PromptCommands, or a direct implementation for 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/`

API call flow

Trace from user input through to tool execution and back:

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

See the Query Engine page for a detailed breakdown of each step.

Code patterns

Recognizing these recurring patterns speeds up reading unfamiliar files.

`buildTool()` — tool factory

Every tool is constructed through the buildTool factory defined in src/Tool.ts:

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

Feature flag gates

Build-time feature flags strip code from the bundle when a feature is disabled:

import { feature } from 'bun:bundle'

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

Anthropic-internal gates

Some features are only enabled for Anthropic employees:

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

Index re-exports

Most directories expose a public API via index.ts:

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

Lazy dynamic imports

Heavy modules are loaded only when needed to keep startup fast:

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

ESM `.js` extensions

Bun convention — all imports use .js extensions even when the source file is .ts:

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

Key files by size

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

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

Study paths

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

Read src/Tool.ts — understand the buildTool interface and permission model
Pick a simple tool like FileReadTool in src/tools/FileReadTool/
Trace how src/QueryEngine.ts calls tools during the tool-call loop
See how permissions are checked in src/hooks/toolPermission/

Path 2: How does the UI work?

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

Path 3: How does the IDE integration work?

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

Path 4: How do plugins extend Claude Code?

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

Path 5: How does MCP work?

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

Grep patterns

Useful ripgrep commands for finding things across the codebase:

# 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/

MCP server for exploration

The repo includes a standalone MCP server in mcp-server/ that lets any MCP-compatible client explore the source code. See the MCP server README for setup instructions. Once connected, you can ask an AI assistant questions such as:

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

The MCP server is the fastest way to explore the source interactively without leaving your AI assistant of choice.

Architecture overview

The full pipeline from CLI entrypoint to terminal UI.

Query Engine

Deep dive into streaming, tool loops, and session management.

MCP

Claude Code as both MCP client and MCP server.

Contributing

How to improve the docs, MCP server, and exploration tooling.

Get Started

Architecture

Subsystems

Guides

Orientation

Finding things

How does tool X work?

How does command X work?

How does feature X work?

API call flow

Code patterns

`buildTool()` — tool factory

Feature flag gates

Anthropic-internal gates

Index re-exports

Lazy dynamic imports

ESM `.js` extensions

Key files by size

Study paths

Grep patterns

MCP server for exploration

See also

Architecture overview

Query Engine

MCP

Contributing

Build docs developers (and LLMs) love

Get Started

Architecture

Subsystems

Guides

​Orientation

​Finding things

​How does tool X work?

​How does command X work?

​How does feature X work?

​API call flow

​Code patterns

​buildTool() — tool factory

​Feature flag gates

​Anthropic-internal gates

​Index re-exports

​Lazy dynamic imports

​ESM .js extensions

​Key files by size

​Study paths

​Grep patterns

​MCP server for exploration

​See also

Architecture overview

Query Engine

MCP

Contributing

Build docs developers (and LLMs) love

Orientation

Finding things

How does tool X work?

How does command X work?

How does feature X work?

API call flow

Code patterns

`buildTool()` — tool factory

Feature flag gates

Anthropic-internal gates

Index re-exports

Lazy dynamic imports

ESM `.js` extensions

Key files by size

Study paths

Grep patterns

MCP server for exploration

See also