Skip to main content
Each path below is a focused reading sequence that answers one core architectural question. Follow them in order — each step builds on the previous.
This path traces the complete lifecycle of a tool — from its type definition, through the Query Engine’s tool-call loop, to the permission check that gates execution.
1

Read src/Tool.ts

Start with the buildTool interface. This file defines every field a tool can declare: input schema, call(), checkPermissions(), isConcurrencySafe(), isReadOnly(), prompt(), and the two render functions. Understanding this interface means you can read any tool in the codebase.
2

Pick a simple tool: FileReadTool

Open src/tools/FileReadTool/. Read FileReadTool.ts for the execution logic, UI.tsx for the terminal rendering, and prompt.ts for the system prompt contribution. FileReadTool is a good starting point because its logic is straightforward — read a path, return content.
3

Trace the tool-call loop in QueryEngine.ts

In src/QueryEngine.ts, find the section that handles tool_use content blocks from the Anthropic API. Follow how the engine resolves the tool by name, calls checkPermissions(), calls call(), and feeds the result back into the next API request. This loop is the heart of how Claude Code executes multi-step tasks.
4

See permission checks in src/hooks/toolPermission/

The permission hooks are the chokepoint for all potentially destructive operations. Read PermissionContext.ts to understand the active mode and rule set, then look at the handlers to see how each tool type implements its approval logic.
The entire terminal UI is built with React and Ink — the same component model as a web app, rendered to the terminal. This path covers the main screen, components, input handling, and the Ink renderer wrapper.
1

Read src/screens/REPL.tsx

This is the main interactive screen — everything the user sees during a normal session lives here. It composes the message history, input box, status bar, and all sub-components. Read it top to bottom to understand the overall layout.
2

Explore src/components/

There are ~140 components in this directory. Pick a few that look interesting — the design system primitives in src/components/design-system/ are a good starting point because other components build on them. Notice that components use Ink’s Box and Text primitives instead of HTML elements.
3

Read src/hooks/useTextInput.ts

This hook captures the user’s keystrokes and manages the input buffer. It handles multi-line input, history navigation, paste events, and Vim mode integration. Understanding this hook explains how Claude Code feels as a terminal application.
4

Check src/ink/

The src/ink/ directory contains the wrapper around Ink’s renderer. It handles how React renders are flushed to the terminal, how full-screen modes are entered and exited, and how the React tree is structured at the top level.
The bridge system connects the CLI to VS Code and JetBrains extensions over a local IPC channel. Permissions, file diffs, and diagnostics flow bidirectionally between the terminal and the IDE.
1

Start at src/bridge/bridgeMain.ts

This is the main loop for bridge mode. It establishes the IPC connection, starts the message dispatcher, and keeps the bridge alive for the duration of the IDE session. Read it to understand the overall lifecycle.
2

Follow src/bridge/bridgeMessaging.ts

This file defines the message protocol — the shape of every message that crosses the bridge in both directions. Understanding the protocol reveals what the IDE extension can request and what Claude Code can push back.
3

Read src/bridge/bridgePermissionCallbacks.ts

When a tool needs user approval in bridge mode, the permission prompt is routed to the IDE instead of the terminal. This file implements those callbacks — how a permission request travels from the Query Engine to the IDE and back.
4

Check src/bridge/replBridge.ts

This file handles bridging a REPL session into the IDE context — maintaining conversation continuity, synchronizing state, and handling session lifecycle events triggered by the extension.
The plugin system lets both built-in and third-party code extend Claude Code’s capabilities — adding tools, commands, or behaviors without modifying core files.
1

Read src/types/plugin.ts

This file defines the plugin API surface — every interface a plugin can implement. Reading it first gives you a complete picture of what plugins are allowed to do before you look at any implementations.
2

See src/services/plugins/

This directory handles plugin discovery, loading, and lifecycle management. Trace how a plugin path is resolved, validated, and registered so its contributions become available to the rest of the system.
3

Check src/plugins/builtinPlugins.ts

The built-in plugins are concrete examples of the plugin API in use. Reading these alongside the type definitions from step 1 shows the gap between the interface and a real implementation.
4

Look at src/plugins/bundled/

Bundled plugins are shipped as part of the Claude Code binary but still go through the plugin loading path. Examining them reveals how plugins interact with core tools and commands, and what the boundary between “core” and “plugin” actually is.
The Model Context Protocol lets Claude Code connect to external MCP servers as a client, expose itself as an MCP server, and build skills from MCP tool definitions.
1

Read src/services/mcp/

This directory implements the MCP client — connecting to external servers, listing their tools, and invoking them. Start here to understand how Claude Code discovers and manages MCP server connections.
2

See src/tools/MCPTool/

MCPTool is the tool that Claude invokes when it wants to use a tool from an MCP server. Read this to understand how MCP tool calls are proxied through the standard buildTool interface.
3

Check src/entrypoints/mcp.ts

This file implements the reverse direction: Claude Code acting as an MCP server itself. External clients (Claude Desktop, VS Code Copilot, Cursor) can connect to Claude Code and call its tools via the MCP protocol.
4

Look at src/skills/mcpSkillBuilders.ts

This file shows how MCP tool definitions are used to automatically generate skills — reusable workflows that wrap MCP server capabilities into named, promptable procedures.

​
Using the MCP server for exploration

This repository ships a standalone MCP server (mcp-server/) that lets any MCP-compatible client explore the source interactively — without reading files manually.

Set up the MCP server

Connect claude-code-explorer-mcp to Claude Code, Claude Desktop, VS Code, or Cursor and explore the source with natural language queries.
Once connected, you can ask an AI assistant questions like:
  • “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 claude-code-explorer-mcp package is published on npm. You can add it to Claude Code with a single command: claude mcp add claude-code-explorer -- npx -y claude-code-explorer-mcp

Build docs developers (and LLMs) love

Get started for freeTalk to us