Claude Code Architecture

Claude Code Architecture

Claude Code is one program that runs a loop. You give it a task, it asks a model what to do, it runs tools, and it repeats until the task is done. Settings, hooks, plugins, skills, MCP servers, and subagents are layers around this loop, and you can change each of them.

Example

You run claude in a folder. The program reads your settings, loads your plugins and MCP servers, builds a prompt, and opens a chat. Run claude --debug to see these steps in the log.

The Big Picture

Source: How Claude Code Works.

Piece	Mark	What it is
Native binary	✅	One program file for each version, kept in ~/.local/share/claude/versions/ with a launcher at ~/.local/bin/claude (Advanced Setup).
Bundled code	🔍	The program carries its JavaScript inside the file and runs it with the Bun runtime.
Command parser	🔍	The commander library builds the tree of commands and flags (see CLI).
Terminal screen	🔍	A React-based renderer draws the chat with ink-box and ink-text elements.
Model loop	✅	Gather context, act, check the result, and repeat (see Turn Pipeline).
Tools	✅	File, search, shell, web, and agent tools (see Tools).
Extensions	✅	Hooks, skills, plugins, MCP, subagents, and mods (see Plugins and Hooks).
Feature flags	🔍	The program asks a flag service (GrowthBook) which experiments are on for you.
Telemetry	✅	OpenTelemetry export is off until you set it up (Monitoring).
Session store	✅	Transcripts live under ~/.claude/projects (see Sessions and Storage).

Where It Runs

The docs list these places: the terminal, the desktop app, IDE extensions, claude.ai/code, Remote Control, Slack, and CI. All of them run the same loop. The code can run on your machine, in the cloud, or on your machine under remote control. Source: How Claude Code Works.

The env var CLAUDE_CODE_ENTRYPOINT names the host. The program sets it when the host did not. The docs show some of the values as app.entrypoint in Monitoring.

Value	Mark	Set when
cli	✅	You start claude in a terminal.
sdk-cli	✅	You use print mode (-p).
sdk-ts, sdk-py, claude-vscode	✅	An SDK or the VS Code extension starts the program.
mcp	🔍	You run claude mcp serve.
claude-code-github-action	🔍	The env var CLAUDE_CODE_ACTION is set.
local-agent, claude-desktop, remote	🔍	A host app sets it.

Processes

Process	Mark	Role
Main process	✅	One for each interactive or print session.
Supervisor (claude daemon)	✅	Runs background sessions so they live on after you close the terminal (Agent View).
Subagent	✅	A separate loop with its own context window (see Subagents).
Hook command	✅	A child process for each command hook.
MCP server	✅	A child process or a remote connection (see MCP).
Search helper	✅	A bundled ripgrep, unless USE_BUILTIN_RIPGREP=0 (Environment Variables).

The supervisor starts on demand and exits when the last client leaves. Its files are ~/.claude/daemon.json and ~/.claude/daemon.log.

Startup Steps

Set CLAUDE_CODE_PROFILE_STARTUP (🔍) to print the time of each step, such as [+12.3ms]. The order below comes from the bundle.

Step	Mark	What happens
Start	🔍	The process sets its entry point and builds the command tree.
Device settings	🔍	Reads device-management settings and the keychain at the same time.
Project root	🔍	Checks --project-config-root, which must be an absolute local folder.
Init	🔍	Loads config, opens storage, starts the feature flag fetch, and starts the fetch of managed settings.
Client data	🔍	Loads a signed configuration document if --client-data-url or CLAUDE_CODE_CLIENT_DATA_URL is set.
Log sinks	🔍	Sets the process title to claude and starts the log and telemetry sinks.
Plugin folders	🔍	Reads --plugin-dir, --plugin-dir-no-mcp, and --plugin-url.
Migrations	🔍	Runs settings migrations.
Managed settings	🔍	Reads policy settings and refuses a version below the minimum.
Plugin early start	🔍	Starts plugin install and load early.
Main action	🔍	Starts telemetry, starts SessionStart hooks (not on resume), checks forced login, and builds the app state.
MCP connect	🔍	Connects MCP servers, then the claude.ai connectors.
Print mode	🔍	Runs the turn and writes the output.
Interactive mode	🔍	Draws the screen and waits for input.

SessionStart and Setup hooks run before the session MCP servers are ready. So an mcp_tool hook cannot run in them (Hooks Reference).

See Also

• Turn Pipeline
• Request Build
• Sessions and Storage
• CLI
• Settings