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. It repeats until the task is done. Settings, hooks, plugins, skills, MCP servers, and subagents are layers around this loop. You can change each of them. This page shows the pieces, the processes, and the order of the startup.
The Big Picture
Source: How Claude Code Works.
| Piece | Status | What it is |
|---|---|---|
| Native binary | Documented: An official docs page names this item. | One program file for each version. It lives in ~/.. A launcher at ~/. points to it. See Advanced Setup in the official docs. |
| Bundled code | Undocumented: Only the program shows this item. It can change without notice. | The program carries its JavaScript inside the file and runs it with the Bun runtime. |
| Command parser | Undocumented: Only the program shows this item. It can change without notice. | The commander library builds the tree of commands and flags. |
| Terminal screen | Undocumented: Only the program shows this item. It can change without notice. | A React-based renderer draws the chat with ink- and ink- elements. |
| Model loop | Documented: An official docs page names this item. | Gather context, act, check the result, and repeat. See The Agent Loop. |
| Tools | Documented: An official docs page names this item. | File, search, shell, web, and agent tools. |
| Extensions | Documented: An official docs page names this item. | Hooks, skills, plugins, MCP, subagents, and mods. |
| Feature flags | Undocumented: Only the program shows this item. It can change without notice. | The program asks a flag service (GrowthBook) which experiments are on for you. You cannot set them. |
| Telemetry | Documented: An official docs page names this item. | OpenTelemetry export is off until you set it up. See Monitoring in the official docs. |
| Session store | Documented: An official docs page names this item. | Transcripts live under ~/.. See Sessions and Storage. |
Where It Runs
The official 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: Environments and Interfaces.
The environment variable CLAUDE_CODE_ENTRYPOINT names the host.
The program sets it when the host did not.
The official Monitoring page shows some of the values as app.entrypoint.
| Value | Status | Set when |
|---|---|---|
cli | Documented: An official docs page names this item. | You start claude in a terminal. |
sdk- | Documented: An official docs page names this item. | You use print mode (-). |
sdk-, sdk-, claude- | Documented: An official docs page names this item. | An SDK or the VS Code extension starts the program. |
mcp | Undocumented: Only the program shows this item. It can change without notice. | You run claude mcp serve. |
claude- | Undocumented: Only the program shows this item. It can change without notice. | The env var CLAUDE_ is set. |
local-, claude-, remote | Undocumented: Only the program shows this item. It can change without notice. | A host app sets it. |
Processes
| Process | Status | Role |
|---|---|---|
| Main process | Documented: An official docs page names this item. | One for each interactive or print session. |
Supervisor (claude daemon) | Documented: An official docs page names this item. | Runs background sessions so they continue after you close the terminal. See Manage Multiple Agents with Agent View in the official docs. |
| Subagent | Documented: An official docs page names this item. | A separate loop with its own context window. |
| Hook command | Documented: An official docs page names this item. | A child process for each command hook. |
| MCP server | Documented: An official docs page names this item. | A child process or a remote connection. |
| Search helper | Documented: An official docs page names this item. | A bundled ripgrep, unless USE_. See Environment Variables in the official docs. |
The supervisor starts on demand and exits when the last client leaves.
Its files are ~/.claude/daemon.json and ~/.claude/daemon.log.
Startup Steps
The order below comes from the program (the bundled code). It runs before your first prompt, so a slow step here makes every start slow.
Then the process loads plugins and servers and starts the turn or the screen.
| Step | Status | What happens |
|---|---|---|
| Start | Undocumented: Only the program shows this item. It can change without notice. | The process sets its entry point and builds the command tree. |
| Device settings | Undocumented: Only the program shows this item. It can change without notice. | Reads device-management settings and the keychain at the same time. |
| Project root | Undocumented: Only the program shows this item. It can change without notice. | Checks --, which must be an absolute local folder. |
| Init | Undocumented: Only the program shows this item. It can change without notice. | Loads config. Opens storage. Starts the feature flag fetch and the fetch of managed settings. |
| Client data | Undocumented: Only the program shows this item. It can change without notice. | Loads a signed configuration document if you set -- or CLAUDE_. |
| Log sinks | Undocumented: Only the program shows this item. It can change without notice. | Sets the process title to claude and starts the log and telemetry sinks. |
| Plugin folders | Undocumented: Only the program shows this item. It can change without notice. | Reads --, --, and --. |
| Migrations | Undocumented: Only the program shows this item. It can change without notice. | Runs settings migrations. |
| Managed settings | Undocumented: Only the program shows this item. It can change without notice. | Reads policy settings and refuses a version below the minimum. |
| Plugin early start | Undocumented: Only the program shows this item. It can change without notice. | Starts plugin install and load early. |
| Main action | Undocumented: Only the program shows this item. It can change without notice. | Starts telemetry. Starts Session hooks (not on resume). Checks forced login. Builds the app state. |
| MCP connect | Undocumented: Only the program shows this item. It can change without notice. | Connects MCP servers, then the claude. connectors. |
| Print mode | Undocumented: Only the program shows this item. It can change without notice. | Runs the turn and writes the output. |
| Interactive mode | Undocumented: Only the program shows this item. It can change without notice. | 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. See the Hooks Reference in the official docs.
What You Can Change at Startup
| Goal | How |
|---|---|
| See how long each startup step takes | Set CLAUDE_. The log shows timings such as [+12.. Undocumented: Only the program shows this item. It can change without notice. |
| Read the startup log | Run claude --. |
| Load a plugin from a folder | Use --, or -- to skip its MCP servers. |
| Use a different project config root | Use -- with an absolute path. |
| Skip the bundled search helper | Set USE_. |
Move ~/. | Set CLAUDE_. |
Example
You run claude --debug in a project folder.
The log shows the settings files it read, the plugins it loaded, and each MCP server it connected.
Then the screen opens and waits for you.
CLAUDE_CODE_PROFILE_STARTUP=1 claude --debug
Related Pages
- The Agent Loop for what happens after startup.
- Request and Cache for what one model call holds.
- Sessions and Storage for the files on disk.
- The CLI, Settings, and Hooks pages in Configure and Extend.