Claude Code 焚诀（二）：Claude Code 是如何启动的？
本文聚焦于Claude Code CLI工具的快速启动机制，深入剖析其如何在终端中实现毫秒级响应。作为Claude Code系列文章的第二篇，我们将详细解读其五阶段启动流水线，揭示一个生产级Agent runtime如何平衡复杂性与启动速度。接下来，让我们一起探索这背后的设计智慧。
Claude Code作为一个运行在终端中的Agent runtime，其内部包含了Query Loop、Tool System、Tasks、State、Memory、Hooks等复杂组件。这看似庞大的系统架构引发了一个关键问题：当用户在终端输入claude命令后，为何输入光标能几乎瞬间出现？Claude Code在启动过程中究竟执行了哪些步骤？
与Web端应用不同，CLI工具无法采用懒加载、UI降级或延迟渲染等策略。Web应用在加载缓慢时可以用loading动画安抚用户，但终端工具的响应延迟会直接冲击用户体验。想象一下，用户只是想查询版本号，却要看着终端长时间等待，这无疑会带来糟糕的使用感受。因此，Claude Code的设计目标是在验证环境、建立安全边界、准备通信层和终端界面的同时，将整个启动流程控制在300毫秒以内。
启动流程
许多项目的启动流程最终会演变成一个庞大的init()函数，将配置读取、环境变量设置、日志初始化、插件加载、命令注册、网络连接和UI渲染等步骤全部混杂在一起。这种设计的弊端在于无法清晰区分哪些步骤必须立即执行、哪些可以延迟、哪些实际上并不需要。
Claude Code采用了截然不同的设计哲学。它将启动流程拆分为五个组件：cli.tsx -> main.tsx -> init.ts -> setup.ts -> replLauncher.ts，形成一条清晰的pipeline流水线。这条pipeline的每一层都是一个逐层收窄的过程，每个组件只执行最小必要的工作，完成后将控制权移交给下一层。
这五层分别回答了五个核心问题：
cli.tsx：判断本次是否需要完整启动？main.tsx：识别哪些慢速I/O操作可以异步执行？init.ts：验证当前环境的可信度并解析配置？setup.ts：确定Claude Code可以使用哪些组件？replLauncher.ts：选择进入Query Loop循环的正确入口？
启动流程的第一步，是先判断有没有必要完整启动。这一设计理念贯穿整个架构。
Phase 0：快速路径调度（cli.tsx）
Claude Code进程最先进入的文件是cli.tsx。此刻，cli.tsx只有一个核心任务：判断本次请求是否需要进入完整Bootstrap流程。这个设计理念类似于操作系统启动中的bootloader角色。
类比传统BIOS + MBR的启动流程：机器通电后，CPU从固定地址0xFFFFFFF0开始执行，这个地址映射到BIOS固件ROM中的jump跳转指令，将CPU引导至真正的BIOS初始化代码。BIOS初始化硬件后，根据启动顺序找到启动盘，读取MBR并加载到内存0x7C00位置，然后跳转执行bootloader代码。Bootloader继续加载GRUB，最终由GRUB加载Linux kernel。
在Claude Code中，cli.tsx扮演着类似的角色。它不会立即加载完整的Claude Code，而是先检查命令行参数argv。对于claude --version、claude --help、claude mcp list等命令，无需加载React、初始化telemetry、读取keychain或加载工具系统。cli.tsx会在fast path中直接处理这些简单指令并退出，采用动态import()按需加载所需模块，实现最小化资源消耗。
Phase 1：异步执行慢 I/O（main.tsx）
当fast path未命中时，cli.tsx进入完整启动流程，首先加载main.tsx。这是第二个关键执行步骤，包含整个bootstrap流程中最核心的性能优化技术：
const mdmPromise = startMDMSubprocess()
const keychainPromise = readKeychainCredentials()
MDM（Mobile Device Management）用于检查企业级设备管理策略，而Keychain则读取macOS系统钥匙串中的安全凭据。这两个I/O操作属于慢速操作，Claude Code将它们设为异步执行，使其与后续模块加载并行推进。这样一来，模块加载的时间被用于等待I/O完成，实现了时间重叠利用。
Phase 2：解析配置与建立信任边界（init.ts）
main.tsx之后进入init.ts，负责解析命令行参数、读取全局和项目配置，并在用户确认信任后应用完整的环境配置。
let initPromise
function init() {
if (!initPromise) {
initPromise = reallyInit()
}
return initPromise
}
采用memoized的init()函数设计，是因为Claude Code有多个调用入口（REPL、claude -p、外部SDK），这种模式避免了重复初始化导致的问题，如配置重复读取和初始化状态重复写入。
init.ts中一个关键概念是trust boundary（信任边界），它关注当前目录、shell环境和项目配置的可信度。Claude Code启动的子进程会继承当前shell的环境变量，存在环境变量被恶意篡改的风险：
- PATH变量：恶意项目可能通过添加假的
bin/git来劫持命令执行 - NODE_OPTIONS：可要求Node.js子进程在启动时额外加载恶意JavaScript
- LD_PRELOAD：在Linux上可预加载恶意共享库
在用户确认信任之前，Claude Code只读取不依赖项目环境的安全信息；确认信任后，才读取PATH、LD_PRELOAD、NODE_OPTIONS等可能影响进程行为的环境变量。
Commander 的 preAction Hook
Commander是Node生态中常用的CLI参数解析库，能够解析flags、subcommands和positional arguments。
fast path与Commander解析的区别在于：--version在语法上是flag，但cli.tsx会直接检查原始process.argv并立即输出版本号退出，此时Commander尚未加载。而--print同样是flag，但需要完整运行环境，因此要走完整init流程。
Claude Code借助Commander的preAction机制：
program.hook("preAction", async (thisCommand) => {
await init(thisCommand)
})
Commander先解析命令结构但不立即执行，而是触发preAction调用一次init(thisCommand)，初始化完成后再执行对应命令的handler。
Phase 3：注册组件（setup.ts）
init()完成后进入setup.ts流程。此时Claude Code已明确：当前配置、目录可信度、权限边界和执行命令。但命令、Agent、Hooks和插件仍需完成注册，这些相互独立的加载任务尽可能并行执行。
setup()执行完成后，Claude Code的各个组件准备就绪。一个值得注意的细节是：Claude Code在此时读取Hooks配置并冻结为不可变快照。这意味着PreToolUse、PostToolUse、Stop、SessionEnd等Hook虽在后续时刻才触发，但依据的是启动时保存的固定配置。这种设计防止了恶意脚本在启动后修改hooks配置，改变工具调用审批规则的风险，与权限系统的设计理念一脉相承。
Phase 4：选择运行入口（replLauncher.ts）
replLauncher.ts是启动流程的最后一站。约七种入口汇聚于此：交互式REPL、--print一次性输出、SDK mode、--resume恢复会话、--continue继续会话、pipe mode和headless无头模式。
前面四层已准备好环境和组件，replLauncher.ts根据配置选择对应入口执行：
- 普通终端对话：进入REPL，使用React/Ink组件树持续更新消息、工具状态、审批提示和输入框
--print模式：适用于脚本、CI和自动化流程，创建headless query loop，不挂载React/Ink组件树，结果流式写入stdout- SDK mode：按协议将事件传到外部供外部程序消费
--resume和--continue：恢复已有会话后进入相同执行循环
这些启动方式共享同一套Agent逻辑，所有入口最终都回归到query loop中。
240ms 是怎么来的
启动过程的各阶段时间分布如下：Fast-path检查约5ms、模块求值约138ms（同时并行慢I/O）、Commander解析约3ms、init()约14ms、setup()约35ms、启动与UI渲染约25ms。总计约240ms，控制在300ms预算线以内。
需要注意的是，这些数字来自代码中的profiling checkpoint，仅用于展示大致结构。现代机器上的warm start大约在240ms级别，cold start会更接近300ms。warm start指操作系统缓存中还有数据，启动更快；cold start则是首次使用或无缓存，需要重新读取。
Claude Code的优秀之处在于将庞大的初始化过程逐层分解，让每一层都职责明确：Phase 0判断是否需要完整启动；Phase 1实现模块加载与I/O异步并行；Phase 2建立可信状态；Phase 3完成组件注册；Phase 4选择运行模式。这种设计是生产级Agent runtime启动方式的典范。