Claude Code Source Code Architecture Overview

If you only look at the source directory, it's easy to be intimidated by the large number of files.
But looking at the main relationships, the architecture of Claude Code is not messy; it can be roughly abstracted into the following diagram:

The responsibility of main.tsx is very heavy; unlike a typical CLI, it doesn't just simply parse parameters and execute a function.
It does a lot of assembly work during the startup phase:

• Pre-warming performance-sensitive modules
• Loading configuration and managed settings
• Initializing authentication, telemetry, and policy restrictions
• Initializing MCP, LSP, plugins, and Skills
• Aggregating commands and tools
• Starting the REPL, non-interactive workflows, or remote sessions based on the mode

Therefore, main.tsx is more like a system bootloader.

import { getSystemContext, getUserContext } from './context.js';
import { launchRepl } from './replLauncher.js';
import { getTools } from './tools.js';
import { filterCommandsForRemoteMode, getCommands } from './commands.js';
import { initializeLspServerManager } from './services/lsp/manager.js';
import { initBuiltinPlugins } from './plugins/bundled/index.js';
import { initBundledSkills } from './skills/bundled/index.js';

This list of imports itself contains a wealth of information.
It shows that the entry layer is not just launching a REPL, but is simultaneously assembling:

• Context system
• Tool system
• Command system
• LSP
• Plugins
• Skills

Thus, the actual positioning of main.tsx in the architecture is the "assembly root."

The value of the startup layer is not just "importing things," but rather centrally deciding:

• What form the current session takes
• Which capabilities to enable
• Which states to pre-load
• Which resources to prepare before entering the main loop

QueryEngine.ts is the heart of Claude Code.
It is responsible for converting a user task into a continuously progressing execution process.

The core objects it manages include:

• Message history
• Tool availability
• Permission denial records
• File cache
• Token and cost statistics
• Abort control
• Session-level state continuity

Without this layer, Claude Code would degrade into "an LLM caller with some tool descriptions."

export class QueryEngine {
  private config: QueryEngineConfig
  private mutableMessages: Message[]
  private abortController: AbortController
  private permissionDenials: SDKPermissionDenial[]
  private totalUsage: NonNullableUsage
  private readFileState: FileStateCache

  constructor(config: QueryEngineConfig) {
    this.config = config
    this.mutableMessages = config.initialMessages ?? []
    this.abortController = config.abortController ?? createAbortController()
    this.permissionDenials = []
    this.readFileState = config.readFileCache
    this.totalUsage = EMPTY_USAGE
  }
}

Just looking at these fields, you can tell that QueryEngine manages much more than just "sending requests to the model"; it also includes:

• Historical messages
• Abort control
• Permission denials
• File cache
• Usage statistics

This is a typical session-level runtime, rather than a one-off request handler.

Tool.ts defines the tool protocol, and tools.ts is responsible for registering and filtering tools.

The role of this layer is to wrap lower-level capabilities into unified tool interfaces callable by the model, such as:

• Reading and writing files
• Bash / PowerShell
• Search and glob
• Reading MCP resources
• Invoking LSP capabilities
• AskUserQuestion
• Agent / Team / Task-related tools

You can think of it as Claude Code's "action layer."

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    WebFetchTool,
    TodoWriteTool,
    WebSearchTool,
    AskUserQuestionTool,
    SkillTool,
    EnterPlanModeTool,
    ...(isEnvTruthy(process.env.ENABLE_LSP_TOOL) ? [LSPTool] : []),
    ListMcpResourcesTool,
    ReadMcpResourceTool,
  ]
}

This code directly shows that Claude Code's capabilities are not abstract imagination, but a clearly registered set of tools.

From here, you can see very intuitively:

• File capabilities
• Shell capabilities
• Search capabilities
• Interaction capabilities
• Skill capabilities
• LSP and MCP capabilities

In addition to model-callable tools, Claude Code also has a large number of explicit commands.
commands.ts aggregates many slash commands, such as:

• Configuration-related
• Session-related
• Review-related
• Plugin-related
• MCP-related
• Plan-related
• Status and statistics-related

The command system serves "explicit user control," while the tool system serves "implicit model execution," each having distinct responsibilities.

The reason this system can "seem to understand the project" lies not just in its tools, but also in its context and state management:

• context.ts is responsible for preparing context such as Git status, CLAUDE.md, date, etc.
• AppStateStore.ts manages UI and session states like REPL, tasks, notifications, remote connections, MCP, plugins, etc.

One is responsible for "what to show the model," and the other is responsible for "the current state of the interface and session."

export const getSystemContext = memoize(async (): Promise<{ [k: string]: string }> => {
  const gitStatus =
    isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) ||
    !shouldIncludeGitInstructions()
      ? null
      : await getGitStatus()

  return {
    ...(gitStatus && { gitStatus }),
  }
})

A key fact can be seen here:
Claude Code actively injects project contexts like Git status into subsequent conversations, which is one of the major reasons it "seems to understand the project."

From the directory structure, we can see that Claude Code has long ceased to be a closed tool, taking on a platform-like form:

• services/mcp/*
• services/lsp/*
• plugins/*
• skills/*
• tools/AgentTool/*
• remote/*

These modules signify that Claude Code is not just executing built-in tools, but is continuously evolving into an "extensible engineering agent platform."

When you see how many directories this repository has, don't rush to think that its "design is messy."
A more reasonable understanding is that Claude Code simultaneously bears four types of system responsibilities:

• Terminal interactive application
• Agent runtime
• Tool and command platform
• External extension integration layer

When you stack these four types of responsibilities together, the directory size naturally won't be small.

When reading, it is recommended to divide the directories into two categories:

• main.tsx
• QueryEngine.ts
• Tool.ts
• tools.ts
• commands.ts
• context.ts
• state/AppStateStore.ts

• services/*
• components/*
• commands/*
• tools/*
• plugins/*
• skills/*
• remote/*

By grasping the core first and then looking at the extensions, efficiency will be much higher.

If you just browse aimlessly through the massive directory, it is easy to get lost.
A more recommended order is:

1. main.tsx
2. QueryEngine.ts
3. Tool.ts
4. tools.ts
5. commands.ts
6. context.ts
7. state/AppStateStore.ts
8. Then proceed to services/mcp, services/lsp, plugins, and skills

This path is much closer to the system's actual backbone.

The source code architecture of Claude Code can be summarized in one sentence:

Use main.tsx to assemble configurations, commands, tools, context, and extension capabilities, and then use QueryEngine to drive the entire engineering task loop.

In the next few articles, we will follow this main line to break things down step by step.