全局视角：不只是 CLI 工具

很多人第一次用 Claude Code，心理模型是：这是个 CLI 工具，在终端里跟 AI 聊天，顺便能改改代码。

这个理解是错的。打开 npm 包，解开 cli.js.map，sourcesContent 字段里躺着完整的 TypeScript 源码。4756 个文件，50+ 顶层模块。你看到的 claude 命令只是一个入口，背后是一套完整的 Agent 操作系统。

代码库规模

最大的几个目录：utils/ 564 个文件（通用工具函数），components/ 389 个（React/Ink UI 组件），commands/ 207 个（斜杠命令实现），tools/ 184 个（Bash/FileRead/Edit 等 Agent 工具），services/ 130 个（外部服务集成）。往下还有 hooks/ 104 个、ink/ 96 个（TUI 框架层）、bridge/ 31 个（远程控制/IDE 集成）、skills/ 20 个、tasks/ 12 个。

关键文件的行数更能说明问题：main.tsx 4683 行，toolExecution.ts 1745 行，query.ts 1729 行，AgentTool.tsx 1397 行，QueryEngine.ts 1295 行，runAgent.ts 973 行，prompts.ts 914 行，Tool.ts 792 行。

每个模块都承担了实质性的逻辑，不是胶水代码。

多入口设计

四个对外入口，每个针对不同场景：cli.tsx 是终端交互入口，init.ts 处理非交互式初始化，mcp.ts 让 Claude Code 本身作为 MCP server 被其他工具调用，sdk/ 则允许 Node.js 程序把它当 library 嵌入。

背后跑的是同一套 Agent 运行时。VS Code 扩展和 JetBrains 插件底层调用的是 bridge/ 里的同一个 agent 核心，不是各自独立实现。

cli.tsx 的 fast-path 分发

启动时间对 CLI 工具很敏感。cli.tsx 的第一件事是按请求类型分流——--version 零模块加载直接打印版本，remote-control 走 bridge/ 控制已有实例，daemon 启动长驻进程，ps/logs/attach/kill 做会话管理，--worktree --tmux 直接 exec 进入隔离工作树。

真正需要运行 Agent 的请求才进 main.tsx：初始化状态、注册工具、构造 ToolUseContext、启动 React/Ink 渲染层，完整走一遍。

命令系统：101 个斜杠命令

src/commands/ 下有 207 个文件，实现了 101 个斜杠命令。加载时按优先级依次叠加：plugin commands 最高，其次 skill commands，再次 bundled skills，最后动态发现的 skills。

同名命令高优先级覆盖低优先级，用户安装的插件因此可以覆盖任何内置行为。Claude Code 本身因此变成了一个可扩展平台，而不只是功能固定的工具。

为什么叫 Agent Operating System

把 Claude Code 定位成 OS，不是比喻，是结构性的描述。

多 agent 并发运行，各自有独立的 abort controller 和生命周期——进程管理是 OS 最基本的职责，Claude Code 有。后台任务跑的时候你可以继续敲其他命令，互不阻塞。

共享的 file state cache 在主 agent 和子 agent 之间保持同步，任何一方的写操作立即反映到其他 agent 的视图里。不会出现”我改了文件但子 agent 还在读旧版本”的情况——这是文件系统抽象。

工具调用不是”模型说调就调”。每次调用经过 14 步 pipeline：权限检查、hooks 扩展点、speculative 风险分类，全套走完才执行。第三章会详细拆这条流水线。

--worktree 给每个任务创建独立的 git worktree，agent 在里面的所有改动不影响主工作区。完成后 merge 还是丢弃，你说了算——进程隔离。

bridge/ 模块处理 IDE 插件和终端进程之间的双向通信。VS Code 扩展里的”Claude”窗口，底层跑的是同一个 agent 核心，不是另一套实现。

五个特征加在一起，才让”给我实现这个功能，我去喝杯水”成为可能。不是在对话框里糊答案，是在运行一个有状态、有工具权限、可以并行的计算过程。

后续章节逐层拆解：第二章看主循环和 prompt 编排，第三章看工具系统和执行 pipeline，第四章看多 agent 调度。

---

参考来源： 本文内容参考 Xiao Tan（@tvytlx）的《Claude Code 源码架构深度解析 V2.0》，基于原报告的分析框架和研究成果整理。