Skip to content

architecture.md

Latest commit

 

History

History
224 lines (147 loc) · 7.63 KB

architecture.md

File metadata and controls

224 lines (147 loc) · 7.63 KB

Architecture

Deep-dive into how Claude Code is structured internally.

High-Level Overview

Claude Code is a terminal-native AI coding assistant built as a single-binary CLI. The architecture follows a pipeline model:

User Input → CLI Parser → Query Engine → LLM API → Tool Execution Loop → Terminal UI

The entire UI layer is built with React + Ink (React for the terminal), making it a fully reactive CLI application with components, hooks, state management, and all the patterns you'd expect in a React web app — just rendered to the terminal.

Core Pipeline

1. Entrypoint (src/main.tsx)

The CLI parser is built with Commander.js (@commander-js/extra-typings). On startup, it:

  • Fires parallel prefetch side-effects (MDM settings, Keychain, API preconnect) before heavy module imports
  • Parses CLI arguments and flags
  • Initializes the React/Ink renderer
  • Hands off to the REPL launcher (src/replLauncher.tsx)

2. Initialization (src/entrypoints/)

File Role
cli.tsx CLI session orchestration — the main path from launch to REPL
init.ts Config, telemetry, OAuth, MDM policy initialization
mcp.ts MCP server mode entrypoint (Claude Code as an MCP server)
sdk/ Agent SDK — programmatic API for embedding Claude Code

Startup performs parallel initialization: MDM policy reads, Keychain prefetch, feature flag checks, then core init.

3. Query Engine (src/QueryEngine.ts, ~46K lines)

The heart of Claude Code. Handles:

  • Streaming responses from the Anthropic API
  • Tool-call loops — when the LLM requests a tool, execute it and feed the result back
  • Thinking mode — extended thinking with budget management
  • Retry logic — automatic retries with backoff for transient failures
  • Token counting — tracks input/output tokens and cost per turn
  • Context management — manages conversation history and context windows

4. Tool System (src/Tool.ts + src/tools/)

Every capability Claude can invoke is a tool. Each tool is self-contained with:

  • Input schema (Zod validation)
  • Permission model (what needs user approval)
  • Execution logic (the actual implementation)
  • UI components (how invocation/results render in the terminal)

Tools are registered in src/tools.ts and discovered by the Query Engine during tool-call loops.

See Tools Reference for the complete catalog.

5. Command System (src/commands.ts + src/commands/)

User-facing slash commands (/commit, /review, /mcp, etc.) that can be typed in the REPL. Three types:

Type Description Example
PromptCommand Sends a formatted prompt to the LLM with injected tools /review, /commit
LocalCommand Runs in-process, returns plain text /cost, /version
LocalJSXCommand Runs in-process, returns React JSX /doctor, /install

Commands are registered in src/commands.ts and invoked via /command-name in the REPL.

See Commands Reference for the complete catalog.

State Management

Claude Code uses a React context + custom store pattern:

Component Location Purpose
AppState src/state/AppStateStore.ts Global mutable state object
Context Providers src/context/ React context for notifications, stats, FPS
Selectors src/state/ Derived state functions
Change Observers src/state/onChangeAppState.ts Side-effects on state changes

The AppState object is passed into tool contexts, giving tools access to conversation history, settings, and runtime state.

UI Layer

Components (src/components/, ~140 components)

  • Functional React components using Ink primitives (Box, Text, useInput())
  • Styled with Chalk for terminal colors
  • React Compiler enabled for optimized re-renders
  • Design system primitives in src/components/design-system/

Screens (src/screens/)

Full-screen UI modes:

Screen Purpose
REPL.tsx Main interactive REPL (the default screen)
Doctor.tsx Environment diagnostics (/doctor)
ResumeConversation.tsx Session restore (/resume)

Hooks (src/hooks/, ~80 hooks)

Standard React hooks pattern. Notable categories:

  • Permission hooks — useCanUseTool, src/hooks/toolPermission/
  • IDE integration — useIDEIntegration, useIdeConnectionStatus, useDiffInIDE
  • Input handling — useTextInput, useVimInput, usePasteHandler, useInputBuffer
  • Session management — useSessionBackgrounding, useRemoteSession, useAssistantHistory
  • Plugin/skill hooks — useManagePlugins, useSkillsChange
  • Notification hooks — src/hooks/notifs/ (rate limits, deprecation warnings, etc.)

Configuration & Schemas

Config Schemas (src/schemas/)

Zod v4-based schemas for all configuration:

  • User settings
  • Project-level settings
  • Organization/enterprise policies
  • Permission rules

Migrations (src/migrations/)

Handles config format changes between versions — reads old configs and transforms them to the current schema.

Build System

Bun Runtime

Claude Code runs on Bun (not Node.js). Key implications:

  • Native JSX/TSX support without a transpilation step
  • bun:bundle feature flags for dead-code elimination
  • ES modules with .js extensions (Bun convention)

Feature Flags (Dead Code Elimination)

import { feature } from 'bun:bundle'

// Code inside inactive feature flags is completely stripped at build time
if (feature('VOICE_MODE')) {
  const voiceCommand = require('./commands/voice/index.js').default
}

Notable flags:

Flag Feature
PROACTIVE Proactive agent mode (autonomous actions)
KAIROS Kairos subsystem
BRIDGE_MODE IDE bridge integration
DAEMON Background daemon mode
VOICE_MODE Voice input/output
AGENT_TRIGGERS Triggered agent actions
MONITOR_TOOL Monitoring tool
COORDINATOR_MODE Multi-agent coordinator
WORKFLOW_SCRIPTS Workflow automation scripts

Lazy Loading

Heavy modules are deferred via dynamic import() until first use:

  • OpenTelemetry (~400KB)
  • gRPC (~700KB)
  • Other optional dependencies

Error Handling & Telemetry

Telemetry (src/services/analytics/)

  • GrowthBook for feature flags and A/B testing
  • OpenTelemetry for distributed tracing and metrics
  • Custom event tracking for usage analytics

Cost Tracking (src/cost-tracker.ts)

Tracks token usage and estimated cost per conversation turn. Accessible via the /cost command.

Diagnostics (/doctor command)

The Doctor.tsx screen runs environment checks: API connectivity, authentication, tool availability, MCP server status, and more.

Concurrency Model

Claude Code uses a single-threaded event loop (Bun/Node.js model) with:

  • Async/await for I/O operations
  • React's concurrent rendering for UI updates
  • Web Workers or child processes for CPU-intensive tasks (gRPC, etc.)
  • Tool concurrency safety — each tool declares isConcurrencySafe() to indicate if it can run in parallel with other tools

See Also