Interactive Playbook

Understand Claude Code from real code paths

Language
Theme

Project Architecture

Claude Code is structured like a runtime platform

The most useful mental model is layered: bootstrap, interactive surface, query runtime, extension surface, policy state, and remote capabilities.

The source snapshot shows a platform-style application rather than a small chat CLI. The key architectural move is separation of concerns: bootstrap and mode routing live in one layer, the REPL and app state in another, query and tool orchestration in another, and permissions/auth/extensibility as cross-cutting layers.

Draw.io-style overview

Claude Code System Overview

Client & entry layerBootstrap layerExecution centerControl planesPlatform capabilities and durable stateEntry SurfacesCLI, SDK, remote control, MCP server modeBootstrap & Runtime RoutingFast paths, init, trust-safe setup, startup prewarmCore Execution Engineinput normalization -> query loop -> model stream -> tool requestsTool Runtimetool pool, orchestration, streaming executor, result shapingPolicy & Authsettings, permissions, auth, config persistenceRemote & Team Layerbridge, direct connect, remote sessions, team memoryInteractive WorkbenchREPL, app state, prompts, tasks, notificationsExtensibilitycommands, skills, plugins, MCP, LSPPersistence & Recoverysession storage, transcripts, resume safetyKey source landmarkscli.tsx, main.tsx, query.ts, tools.ts, permissions.ts, mcp/client.ts

Diagram views

Runtime map

The primary runtime stack from bootstrap through query and tools.

Runtime map

Source anchors

Bootstrap edge

Start with the CLI bootstrap to understand mode routing and fast paths.

  • src/entrypoints/cli.tsx
  • src/main.tsx

Turn entry

Input normalization is the transition from user intent to runtime work.

  • src/utils/processUserInput/processUserInput.ts

Core runtime

The query loop and tool runtime are the system center of gravity.

  • src/query.ts
  • src/services/tools/toolOrchestration.ts
01

Bootstrap & Runtime Modes

Fast-path entrypoints decide whether Claude Code behaves like a full interactive CLI, a headless engine, a bridge process, or an MCP server.

src/entrypoints/cli.tsxsrc/main.tsxsrc/entrypoints/init.ts
02

Interactive Surface

The REPL and supporting UI state render conversation history, task status, tool output, permissions, and remote controls.

src/replLauncher.tsxsrc/screens/REPL.tsxsrc/state/AppStateStore.ts
03

Query & Tool Runtime

User input is normalized, streamed through query orchestration, and converted into ordered, concurrency-aware tool execution.

src/query.tssrc/QueryEngine.tssrc/services/tools/toolOrchestration.ts
04

Extensibility Layer

Commands, skills, plugins, MCP servers, and LSP integrations are all loaded into the same runtime surface and filtered by policy.

src/commands.tssrc/tools.tssrc/utils/plugins/pluginLoader.tssrc/services/mcp/client.ts
05

Policy, Auth & Persistence

A deep settings and permission system governs what the runtime is allowed to do, how it authenticates, and how sessions resume safely.

src/utils/permissions/permissions.tssrc/utils/auth.tssrc/utils/config.tssrc/utils/sessionStorage.ts
06

Remote & Team Capabilities

Claude Code can act as a remote-control target, manage remote sessions, sync team memory, and expose itself over MCP.

src/bridge/bridgeMain.tssrc/remote/RemoteSessionManager.tssrc/services/teamMemorySync/index.tssrc/entrypoints/mcp.ts

System boundary

Local runtime first

Claude Code starts as a local process, but the architecture leaves room for remote control, bridge mode, and MCP exposure.

Design principle

Composition over one giant loop

Commands, skills, plugins, tools, MCP resources, and settings are composed into the active runtime rather than hard-coded into one mode.

Reading hint

Trace one request across layers

The architecture becomes much easier once you track a single user turn across UI, query, permissions, tools, and persistence.