Claude Code CLI

Claude Code is an AI-powered command-line interface for software engineering tasks. It operates as an agentic coding assistant that can read, write, and reason about code in real-time, directly from your terminal. Built on Anthropic's Claude models, it provides an interactive REPL as well as a headless SDK mode for programmatic integration. This documentation covers the internal source code architecture -- the tools, services, state management, query pipeline, and extension systems that make it all work. Whether you are contributing to the CLI, building integrations on top of it, or just curious about how an agentic coding tool is put together, you will find detailed breakdowns of every major subsystem here.

High-Level Architecture

The following diagram shows how the major subsystems connect during a typical session:

CLI Entry (cli.tsx)
  |
  v
Initialization (init.ts)
  |-- Config & Environment
  |-- Shutdown Handlers
  |-- Telemetry & OAuth
  |
  v
Main Bootstrap (main.tsx)
  |-- MDM Subprocess (parallel)
  |-- Keychain Prefetch (parallel)
  |-- File System & Project Setup
  |-- Prefetch (API, MCP, GrowthBook)
  |
  +---> Interactive Mode (REPL)        Headless Mode (SDK / -p flag)
  |       |                               |
  |       v                               v
  |     UI Rendering (Ink/React)       QueryEngine.submitMessage()
  |       |                               |
  +-------+-------------------------------+
          |
          v
    Query Pipeline (query.ts)
      |-- Permission Check
      |-- Message Normalization
      |-- Context Building (System Prompt, User/System Context)
      |-- API Call (Streaming)
      |-- Tool Orchestration (StreamingToolExecutor)
      |-- Stop Hooks
      |-- Response Streaming (AsyncGenerator<StreamEvent | Message>)
          |
          v
    Tool Execution
      |-- Built-in Tools (Bash, Edit, Read, Write, Grep, Glob, ...)
      |-- MCP Tools (external servers)
      |-- Agent Tools (sub-agents)
      |-- Plugin Tools

Key Concepts

Tools

Tools are the primary mechanism through which Claude interacts with the file system, executes commands, and performs actions. Each tool defines its own input schema, permission requirements, and execution logic. Tools range from file operations (Read, Write, Edit) to shell execution (Bash) to search (Grep, Glob) and beyond.

Services

Services provide shared infrastructure that tools and the query pipeline depend on. This includes the API client for communicating with Claude models, MCP (Model Context Protocol) server management, analytics and telemetry, compaction (context window management), and LSP integration.

Commands

Commands are slash-commands available in the interactive REPL (e.g., /help, /compact, /config). They are registered declaratively and can modify session state, trigger actions, or display information.

Queries

The query pipeline is the core agentic loop. It takes a user message, builds the full prompt context (system prompt, tools, conversation history), streams the response from the API, orchestrates any tool calls the model makes, and yields the results back as an async generator of StreamEvent and Message objects.

State

State is split into two layers:

• Bootstrap State -- mutable global state in bootstrap/state.ts that holds session-level values like cwd, sessionId, model overrides, telemetry counters, and feature flags. Set once during startup and mutated sparingly.
• AppState -- an immutable (via DeepImmutable) store managed through AppStateStore.ts that drives the UI. It holds settings, model selection, tool permissions, MCP connections, plugin state, and UI-specific flags.

Permissions

The permission system controls which tools the model can invoke and under what conditions. It supports multiple modes (default, auto, bypass) and integrates with policy limits, managed settings, and per-tool permission contexts.

Documentation Sections