Claude Code - Project Overview

Technology Stack

Technology	Version / Notes
TypeScript	5.x, strict mode
React	19.x, with React Compiler output
Bun	Runtime + bundler, bun:bundle feature flags for DCE
Ink (custom fork)	Full TUI framework in src/ink/, not the npm package
@anthropic-ai/sdk	Claude API client, Beta Messages API
@modelcontextprotocol/sdk	MCP server/client protocol
@commander-js/extra-typings	CLI argument parsing
Zod v4	Runtime type validation & schema definition
lodash-es	Utility functions (memoize, mergeWith, uniqBy, etc.)
OpenTelemetry	Telemetry/tracing (sdk-logs, sdk-metrics, sdk-trace-base)
GrowthBook	Feature flags & A/B testing
chalk	Terminal color output
Yoga (WASM)	Ink layout engine, CSS Flexbox implementation

Architecture Pattern

Event-driven Async Generator Pipeline with Layered Dependency Injection

The system is not traditional MVC. It's built around a "message stream pipeline":

CLI (commander) -> main.tsx -> query() generator -> API -> Tool execution -> Result
                                  ^                                          |
                                  +------------- loop ----------------------+

Entry Points & Startup Flow

Primary Entry: src/entrypoints/cli.tsx

• Zero-dependency fast-path dispatcher
• Handles --version, --daemon-worker, bridge, daemon before loading full CLI
• Minimizes startup time by deferring heavy imports via dynamic import()
• ~250 lines

Initialization: src/entrypoints/init.ts

• Core app initialization: config system, env vars, mTLS, telemetry, LSP, policy
• Two-phase: pre-trust-dialog and post-trust-dialog
• Memoized to execute only once
• ~400 lines

Main Function: src/main.tsx

• Parses all Commander.js arguments
• Handles all run modes: interactive REPL, headless, MCP server, remote, print
• Assembles ToolUseContext (the primary dependency injection object)
• Calls launchRepl() or runHeadless()
• ~4000+ lines (the "god function")

Bootstrap State: src/bootstrap/state.ts

• Global singleton state store
• Holds session ID, CWD, model config, telemetry counters, OAuth tokens
• ~80 getter/setter functions, ~1759 lines
• Comment warns: "DO NOT ADD MORE STATE HERE"

Core Data Flow

1. Startup Path

cli.tsx::main() -> fast-path dispatch -> main.tsx::main() -> init()
-> parse CLI args -> build AppState + ToolUseContext -> launchRepl() or ask()

2. Interactive Session Path

launchRepl() -> React + Ink render <App><REPL/></App>
-> user types in PromptInput -> REPL.tsx calls QueryEngine.submitMessage()
-> query() generator -> claude.ts API call -> streaming StreamEvent
-> tool calls trigger toolOrchestration.ts -> tool results appended
-> loop continues until stop_reason === "end_turn"

3. Tool Execution Path

tool.checkPermissions() -> permission dialog (interactive) or auto-decision
-> tool.call() -> ToolResult -> serialized as UserMessage tool_result
-> appended to conversation -> API loop continues

4. Sub-Agent Path

AgentTool.call() -> runAgent() -> clone ToolUseContext (fork)
-> independent query() loop -> results aggregated -> return to parent

5. CLAUDE.md Injection Path

context.ts::getUserContext() -> scan CWD to home path -> read CLAUDE.md files
-> memoize cache -> inject into system prompt before each API call

Key Configuration

• CLAUDE.md files: Project/user instructions injected into system prompt (hierarchical: project > user > global)
• settings.json: Multi-source settings merge (user-level ~/.claude/settings.json, project-level .claude/settings.json, enterprise MDM/HKCU, CLI flags, remote hosted)
• Feature flags: bun:bundle compile-time DCE + GrowthBook runtime overrides
• Permission modes: 5 modes defined in src/types/permissions.ts (e.g., default, plan, yolo, etc.)
• Hooks: Pre/post tool-use hooks configured in settings

Cross-Cutting Concerns

• Permission system: ToolPermissionContext (immutable) flows through the entire tool call chain
• Telemetry: GrowthBook feature flags + OpenTelemetry + logEvent() throughout
• Context compaction: services/compact/ auto-triggers when context window approaches limit
• Error handling: AbortController signal propagation + try/catch + gracefulShutdown registry
• Multi-agent coordination: Coordinator Mode manages worker agent networks, permissions proxy from worker to leader UI

Build & Distribution

• Runtime: Bun (not Node.js)
• Bundler: Bun's built-in bundler with bun:bundle feature flags
• Dead Code Elimination: feature('FLAG') calls are evaluated at build time; unreachable branches are removed
• React Compiler: Some .tsx files contain React Compiler output (_c() cache slots)
• Source Maps: Embedded as base64 comments in compiled .tsx files