REVERSE ENGINEERED / SOURCE-LEVEL ANALYSIS

Understanding Claude Code
从源码看 AI 编程智能体

深入 Anthropic 官方 CLI 工具的内部实现 — 从架构设计到 Agent Loop,从 54 个工具系统到多层权限模型,完整拆解一个工业级 AI 编程智能体是如何构建的。

54
内置工具
88+
Feature Flags
Bun
运行时
6
权限模式
v1.1.0
版本

核心架构一览

Claude Code 的请求处理流程:从用户输入到 API 调用,再到工具执行的完整链路。

入口
cli.tsx
polyfills + bootstrap
CLI 解析
main.tsx
Commander.js
交互界面
REPL.tsx
React + Ink
查询引擎
QueryEngine
会话管理
API 调用
query()
流式响应
工具执行
Tools
54 个工具

深度分析章节

从不同维度拆解 Claude Code 的设计与实现。

Chapter 01

整体架构

入口引导流程、模块组织、运行时 (Bun)、构建系统、UI 渲染层 (React + Ink)、状态管理 (Zustand)。

Chapter 02

Agent Loop

核心 query() 循环、流式响应处理、工具调用编排、turn 管理、错误恢复与重试策略。

Chapter 03

工具系统

54 个内置工具全览:文件操作、Shell 执行、搜索、Web 访问、任务管理,以及工具注册与条件加载机制。

Chapter 04

权限与安全

6 种权限模式、多层规则来源 (flag → user → project → policy)、LLM 分类器自动审批、危险命令检测。

Chapter 05

多智能体

子 Agent 类型 (Explore/Plan/General)、Agent 隔离 (Worktree/Remote)、Fork 机制、Team Swarm 多 Agent 协作。

Chapter 06

上下文管理

System Prompt 构建、CLAUDE.md 加载、Memory 系统、Compaction 压缩策略、Token Budget 管理。

Chapter 07

Hook 系统

15+ 生命周期事件、PreToolUse/PostToolUse 钩子、权限拦截、会话钩子、异步 Hook 注册与响应。

Chapter 08

MCP 协议

Model Context Protocol 集成、MCP Server 生命周期管理、资源读取、工具代理、Prompt 模板。

Chapter 09

API 与模型

多 Provider 支持 (Anthropic/Bedrock/Vertex/Azure)、流式 API 调用、Thinking 模式、Fallback 策略。

Chapter 10

终端 UI

Ink 框架 (React in Terminal)、自定义 reconciler、虚拟列表渲染、消息组件、权限对话框。

Chapter 11

对比:Codex CLI

Rust vs TypeScript、OS 内核沙箱 vs LLM 分类器、81 crate vs 54 工具 — 两种截然不同的安全哲学。

Chapter 12

内部机制

88+ Feature Flags、bun test (418 测试文件)、Biome 代码检查、Computer Use 完整实现、Session 管理。

Chapter 13

Bridge / 远程控制

src/bridge/ 34 文件、多会话管理、JWT 认证、Worktree 隔离、REPL 协议、Background Sessions。

Chapter 14

设计思想解读

五条核心原则、动态 System Prompt 拼装、Agent 分工、工具治理 14 步链路、上下文经济学、生命周期管理。

核心设计决策

TypeScript + Bun

选择 TypeScript 而非 Rust/Go,借助 Bun 的高性能运行时,实现快速迭代。代码分割构建,输出 ~450 chunk 文件。

LLM 驱动的安全

与 Codex CLI 的 OS 级沙箱不同,Claude Code 用额外一次 LLM 调用来判断命令安全性 — 灵活但依赖模型能力。

React in Terminal

使用 Ink (React for CLI) 构建终端 UI,组件化开发,配合 React Compiler 进行自动优化。

Generator-based Streaming

核心 query() 函数使用 AsyncGenerator,实现真正的流式处理 — 事件逐个 yield,工具结果实时返回。

多层权限架构

6 种权限模式 + 7 层规则来源,从 CLI flag 到组织策略,每一层都可以 allow/deny/ask 任何工具。

MCP 原生集成

内置 Model Context Protocol 支持,MCP Server 作为可插拔的工具源,支持资源读取、工具代理、Prompt 模板。

项目目录结构