整体架构

Claude Code 是一个用 TypeScript 编写、运行在 Bun 上的终端 AI 编程助手。它的架构分为几个清晰的层次。

技术栈概览

运行时 & 构建系统

Claude Code 完全基于 Bun 运行时，而非 Node.js。所有导入、构建和执行都使用 Bun 的原生 API。

# 安装依赖
bun install

# 开发模式 (通过 -d flags 注入 MACRO defines)
bun run dev    # 默认启用 BUDDY, TRANSCRIPT_CLASSIFIER, BRIDGE_MODE 等 6 个 feature

# 构建 (代码分割, 输出 dist/cli.js + ~450 chunk files)
bun run build  # build.ts 执行 Bun.build() with splitting: true

# 测试 & Lint
bun test                  # 运行全部 418 个测试文件
bun run lint              # Biome 代码检查

# Pipe 模式
echo "say hello" | bun run src/entrypoints/cli.tsx -p
    

启动引导流程

从用户执行 claude 命令到进入交互界面，经历以下步骤：

架构分层

状态管理

Claude Code 使用多层状态管理：

• AppState (src/state/AppState.tsx) — 中央状态类型和 Context Provider。包含消息列表、工具池、权限配置、MCP 连接等。
• Store (src/state/store.ts) — Zustand 风格的状态存储，用于 AppState 的读写。
• Session Singletons (src/bootstrap/state.ts) — 模块级单例：Session ID、当前工作目录、项目根路径、Token 计数。

// AppState 核心字段
interface AppState {
  messages: Message[]           // 对话消息列表
  tools: Tool[]                 // 可用工具列表
  permissionContext: PermCtx    // 权限配置
  mcpClients: McpClient[]       // MCP 服务器连接
  apiConfig: ApiConfig          // API 配置 (provider, model)
  sessionId: string            // 会话唯一标识
  // ... 更多字段
}
    

UI 渲染层

Claude Code 的终端 UI 基于 Ink — 一个在终端中渲染 React 组件的框架。

• ink.ts — Ink 渲染包装器，注入 ThemeProvider。
• ink/ — 自定义 Ink 框架（fork/内部版本）：自定义 reconciler、hooks (useInput, useTerminalSize)、虚拟列表渲染。
• components/ — 终端 UI 组件：App.tsx (根 Provider)、Messages.tsx (消息渲染)、PromptInput/ (用户输入)、permissions/ (权限确认 UI)。

Feature Flag 系统 (88+)

通过 import { feature } from 'bun:bundle' 实现编译时功能门控。在 Dev 模式下通过环境变量 FEATURE_<FLAG>=1 启用特定功能。

// 统一从 bun:bundle 导入
import { feature } from 'bun:bundle';

if (feature('BRIDGE_MODE')) {
  // 仅在 FEATURE_BRIDGE_MODE=1 时启用
}

// Dev 默认启用: BUDDY, TRANSCRIPT_CLASSIFIER, BRIDGE_MODE,
//               AGENT_TRIGGERS_REMOTE, CHICAGO_MCP, VOICE_MODE
// Build 默认启用: AGENT_TRIGGERS_REMOTE, CHICAGO_MCP, VOICE_MODE
// 手动启用: FEATURE_PROACTIVE=1 bun run dev