Disha

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

Disha

Architecture

High-Level Overview

Core Pipeline

1. Entrypoint (src/main.tsx)

2. Initialization (src/entrypoints/)

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

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

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