@mseep/claude-code-source
v2.1.152
Published
Claude Code source - local runnable setup for learning
Downloads
169
Readme
本仓库包含 Claude Code（Anthropic 的 AI 编程 CLI）的提取源代码，以及 18 篇原创深度分析文章（中英双语）对其架构进行全面拆解。源代码来自公开渠道，严格仅供学习和研究用途。
源代码的所有知识产权完全归 Anthropic, PBC 所有。
跟随官方更新，保持最新版本。 本仓库跟随 Claude Code 官方发布节奏，始终与最新版本保持同步。官方每次发布新版本后，我们都会针对其 changelog 中面向用户、可落地的部分进行对应更新。每个版本的具体变更记录（包括本仓库已应用的改动和仅存在于官方的改动）请见
CHANGELOG.md。
免责声明 · 为什么研究 · 架构总览 · 深度分析 · 从源码运行 · 技术栈 · 项目结构 · 版权声明
免责声明
重要：使用前请阅读
本仓库严格仅供学习和研究用途。
- 来源：本仓库引用的源代码来自公开渠道，包括 instructkr/claw-code。从源码运行的配置基于 JiaranI/start-claude-code。其中包含 Anthropic 公司的 Claude Code 产品的源代码。
- 知识产权：源代码的所有知识产权完全归 Anthropic, PBC 所有。本仓库不主张对原始代码的任何所有权、著作权或权利。
- 用途：本仓库仅作为学习材料提供，用于理解 AI Agent 系统架构和工程设计模式，面向学术研究、技术学习和教育讨论。
- 禁止用途：本仓库及其内容不得用于：
- 任何形式的商业用途
- 构建竞品产品或服务
- 再分发或重新打包源代码
- 任何违反 Anthropic 服务条款 或适用法律的行为
- 分析文章：深度分析文章（
claude-code-deep-analysis/）是仓库维护者撰写的原创评论和分析。文章中包含的代码片段用于评论、批评和教育目的，但这些文章不构成法律建议。 - 侵权处理：如您是 Anthropic 的代表或认为本仓库侵犯了任何知识产权，请联系我们，我们将立即删除相关内容。您也可以通过 GitHub 的 DMCA 流程 提交侵权通知。
- 免责条款：本仓库按"现状"提供，不附带任何形式的保证。维护者不对因使用本材料而产生的任何后果承担责任。
为什么研究这个代码库？
Claude Code 是目前可公开观察到的最复杂的生产级 AI Agent 系统之一。与玩具框架和演示 Agent 不同，它为真实世界的数小时编程会话而设计，具备企业级可靠性。研究它能揭示任何教程都不会教的实战工程决策：
| 设计决策 | 洞察 |
|:---|:---|
| 循环优于图 | 用 while(true) 循环取代 DAG 工作流编排——更简单、更灵活、运行时更易推理 |
| 递归优于编排 | 子 Agent 递归调用 query()，自动继承压缩、错误恢复和流式处理 |
| 模型做决策，框架做执行 | 框架负责安全约束（并发、副作用、权限），所有推理留在模型中 |
| 为 4 小时会话而设计 | 四层上下文压缩和三级 413 错误恢复——在演示中看不见，在生产中不可或缺 |
| 不可变性即成本优化 | 不可变 API 消息最大化 prompt caching 命中率，长会话成本降低约 80% |
架构总览
CLI / VS Code / IDE 扩展
│
▼
┌───────────────────────┐
│ 入口 (cli.tsx) │
│ 快速路径路由 │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ QueryEngine │
│ 会话管理 │
│ API 客户端封装 │
└───────────┬───────────┘
│
┌───────────────────▼───────────────────┐
│ query() — 核心 Agent 循环 │
│ ┌─────────────────────────────────┐ │
│ │ while (true) { │ │
│ │ messages = buildPrompt() │ │
│ │ response = stream(messages) │ │
│ │ tools = extractToolCalls() │ │
│ │ if (!tools) break │ │
│ │ results = executePar(tools) │ │
│ │ messages.push(results) │ │
│ │ maybeCompress(messages) │ │
│ │ } │ │
│ └─────────────────────────────────┘ │
└──────┬──────────┬──────────┬──────────┘
│ │ │
┌────────▼──┐ ┌────▼────┐ ┌───▼────────┐
│ 45+ 工具 │ │ 权限 │ │ 上下文 │
│ Bash, Edit │ │ 系统 │ │ 压缩 │
│ Glob, Grep │ │ 5 种 │ │ 4 层 │
│ MCP, LSP… │ │ 模式 │ │ + 413 恢复 │
└────────────┘ └─────────┘ └────────────┘关键指标
| 指标 | 数量 |
|:---|:---|
| 核心 Agent 循环 (query.ts) | 1,729 行 |
| 主 UI 组件 (main.tsx) | 4,683 行 |
| 工具实现 | 45+ |
| Slash 命令 | 87+ |
| React UI 组件 | 146+ |
| 工具函数 | 564+ |
| React Hooks | 85+ |
| 服务模块 | 38 |
| Feature Flag | 89 |
| System Prompt 组装 (prompts.ts) | 54.3 KB |
深度分析系列
我们撰写了 18 篇原创文章，对每个核心子系统进行源码级深度拆解。每篇文章均提供中文和英文版本。
进入分析系列 (中文) → ｜ Enter the analysis series (EN) →
Part 1：核心 Agent 引擎
| # | 主题 | 中文 | English | |:--|:------|:-----|:--------| | 00 | 核心结论 | 中文 | EN | | 01 | 入口流程 | 中文 | EN | | 02 | 主循环 | 中文 | EN | | 03 | 流式处理 | 中文 | EN | | 04 | 工具编排 | 中文 | EN | | 05 | 权限系统 | 中文 | EN | | 06 | 子Agent | 中文 | EN | | 07 | 上下文窗口 | 中文 | EN | | 08 | 消息类型 | 中文 | EN | | 09 | 不可变消息 | 中文 | EN | | 10 | 架构图 | 中文 | EN | | 11 | 设计哲学 | 中文 | EN |
Part 2：外围子系统
| # | 主题 | 中文 | English | |:--|:------|:-----|:--------| | 12 | MCP 集成 | 中文 | EN | | 13 | Memory 系统 | 中文 | EN | | 14 | System Prompt | 中文 | EN | | 15 | Session 与 Bridge | 中文 | EN | | 16 | 工具实现 | 中文 | EN | | 17 | Hook 系统 | 中文 | EN |
从源码运行
本仓库支持从源码本地启动 Claude Code（功能有所缩减）。持续跟随上游发布，当前已对齐 2.1.123（详见 CHANGELOG.md）。
环境要求
| 依赖 | 说明 |
|:---|:---|
| Node.js >= 18 | 运行 setup 脚本 |
| Bun >= 1.0 | 运行 Claude Code（setup 脚本会自动安装） |
| 认证方式 | Claude Pro/Max/Team 订阅（OAuth）、API Key（sk-ant-xxx）、ChatGPT 订阅、或 OpenAI API Key |
快速开始
# 1. 安装依赖并设置 shim
node scripts/setup.mjs
# 2. 使用 Claude 订阅账号登录（会打开浏览器）
./start.sh login
# 3. 启动
./start.shexport ANTHROPIC_API_KEY="sk-ant-xxx"
./start.sh如果你有 ChatGPT Plus/Pro/Business/Enterprise 订阅，可以直接使用 GPT-5.5 作为 Agent 模型，无需 API Key：
# 1. 使用 ChatGPT 账号登录（会打开浏览器）
./start.sh chatgpt-login
# 2. 使用 GPT-5.5 启动
./start.sh --model gpt5.5可用的 GPT 模型别名：
| 别名 | 解析为 | 所需订阅 |
|:---|:---|:---|
| gpt5.5 | chatgpt:gpt-5.5 | Plus / Pro / Business / Enterprise |
| gpt5.5-pro | chatgpt:gpt-5.5-pro | Pro / Business / Enterprise |
| gpt5.4 | chatgpt:gpt-5.4 | Plus / Pro / Business / Enterprise（旧版） |
| gpt5.4-mini | chatgpt:gpt-5.4-mini | 任意付费订阅 |
| gpt5.4-nano | chatgpt:gpt-5.4-nano | 任意付费订阅 |
也可以使用完整格式：--model chatgpt:gpt-5.5
export OPENAI_API_KEY="sk-xxx"
./start.sh --model openai:gpt-5.5同样支持其他 OpenAI 兼容 Provider：
export DEEPSEEK_API_KEY="sk-xxx"
./start.sh --model deepseek:deepseek-chat
export MISTRAL_API_KEY="xxx"
./start.sh --model mistral:mistral-large-latest完全在本地 Ollama 模型上运行 Claude Code —— 无需 API Key，不向 Anthropic 或 OpenAI 发起任何请求。启动器会拉起内置的 Anthropic→Ollama 代理（scripts/ollama-proxy.mjs），把 CLI 指向它。
# 1. 安装并启动 Ollama (https://ollama.com)
ollama serve
# 2. 拉取一个支持工具调用的模型
ollama pull qwen2.5-coder:7b
# 3. 在本地模型上启动 Claude Code
./start-ollama.sh qwen2.5-coder:7b如果模型没有原生工具调用能力，设置 PROMPTED_TOOLS=1：
PROMPTED_TOOLS=1 ./start-ollama.sh phi3:minirem Windows 下使用 API Key（OAuth 登录需要 macOS/Linux 的 start.sh）
set ANTHROPIC_API_KEY=sk-ant-xxx
bun src/entrypoints/cli.tsx- ripgrep：setup 脚本中的 tar 解压在 Windows 上可能失败。请手动安装 ripgrep 并确保
rg在 PATH 中。 - Bun 路径：安装 Bun 后需要重启终端，或手动将
%USERPROFILE%\.bun\bin添加到 PATH。 - OAuth 登录：
./start.sh login仅适用于 macOS/Linux。Windows 下运行bun src/entrypoints/cli.tsx auth login --claudeai。
创建的 Shim 文件
以下文件是为了让源码可运行而创建的，不属于原始源码：
| 文件 | 作用 |
|:---|:---|
| package.json | 从 import 语句逆向工程出的 100+ 依赖声明 |
| tsconfig.json | TypeScript 配置，含 baseUrl 和 .js → .ts/.tsx 路径解析 |
| bunfig.toml | Bun 配置，指定 preload 插件 |
| preload.ts | 核心 shim：bun:bundle 模拟（feature() 返回 false）、MACRO.* 全局变量注入 |
| scripts/setup.mjs | 一键安装：依赖安装、私有包 stub、缺失文件生成、ripgrep 下载 |
| start.sh | macOS/Linux 启动脚本，支持 OAuth 登录（./start.sh login）、多种凭证检测（Keychain/文件/环境变量）、第三方代理自动检测、Bun 编译缓存自动清理 |
工作原理
| 问题 | 解决方案 |
|:---|:---|
| bun:bundle 编译时 API | preload.ts 提供运行时 shim，feature() 全部返回 false |
| 89 个 Feature Flag | 全部禁用（所有 feature-gated 代码路径不执行） |
| MACRO.* 编译时宏 | preload.ts 中定义为 globalThis.MACRO 全局变量 |
| from 'src/...' 导入 | 源码放在 src/ 目录下，tsconfig.json 中 baseUrl: "." 使路径自然解析 |
| 无 package.json | 已从 import 语句逆向工程出 100+ 依赖 |
| @ant/* 内部包 | scripts/setup.mjs 创建空实现 stub |
不可用的功能（缺失私有包）
| 功能 | 缺失的包 | 说明 |
|:---|:---|:---|
| Computer Use（电脑操控） | @ant/computer-use-mcp | 截屏、鼠标点击、键盘输入等 |
| 原生键鼠输入 | @ant/computer-use-input | Rust/enigo 原生绑定 |
| macOS 截屏/窗口管理 | @ant/computer-use-swift | Swift 原生绑定，仅 macOS |
| Chrome 浏览器集成 | @ant/claude-for-chrome-mcp | Chrome 扩展 MCP server |
| 沙箱运行时 | @anthropic-ai/sandbox-runtime | 命令执行沙箱 |
| MCP Bridge | @anthropic-ai/mcpb | MCP 协议桥接 |
由于 feature() 在运行时返回 false，以下功能全部被禁用：
ABLATION_BASELINE AGENT_MEMORY_SNAPSHOT AGENT_TRIGGERS BRIDGE_MODE BUDDY BUILDING_CLAUDE_APPS CCR_AUTO_CONNECT COORDINATOR_MODE DAEMON DIRECT_CONNECT DUMP_SYSTEM_PROMPT FORK_SUBAGENT HISTORY_PICKER KAIROS MCP_SKILLS MONITOR_TOOL NATIVE_CLIPBOARD_IMAGE PERFETTO_TRACING QUICK_SEARCH SSH_REMOTE STREAMLINED_OUTPUT TEAMMEM TEMPLATES TERMINAL_PANEL TORCH ULTRAPLAN ULTRATHINK VOICE_MODE WEB_BROWSER_TOOL WORKFLOW_SCRIPTS 等共 89 个。
构建流程推断
TypeScript 源码
│
├─ Bun bundler (bun build)
│ ├─ 注入 MACRO.* 常量 (--define)
│ ├─ 解析 feature() 调用 → 设置 89 个 feature flag 的 true/false
│ ├─ Dead Code Elimination → 移除未启用 feature 的代码分支
│ └─ 打包为单文件 JS bundle
│
├─ 可选：Bun compile → 编译为单文件可执行二进制
│
└─ 发布到 npm (@anthropic-ai/claude-code)故障排查
| 错误 | 解决方案 |
|:---|:---|
| Cannot find module 'src/...' | 确认源码在 src/ 目录下，且 bunfig.toml 存在 |
| Missing 'default' export in module '*.md' | 运行 node scripts/setup.mjs 重新生成缺失的 stub 文件 |
| Cannot find package '@ant/...' | 运行 node scripts/setup.mjs 重新创建 stub |
| bun: command not found | 安装 Bun：curl -fsSL https://bun.sh/install \| bash（或重启终端） |
| No authentication found | 运行 ./start.sh login 使用 OAuth 登录，或 export ANTHROPIC_API_KEY="sk-ant-xxx" 使用 API Key |
| 使用非 Anthropic 代理 | start.sh 会自动检测并设置；手动启动时需设置 DISABLE_PROMPT_CACHING=1 和 DISABLE_INTERLEAVED_THINKING=1 |
| 只能在一个目录启动 / 移动源码后卡死 | Bun 按绝对路径缓存编译结果。start.sh 会自动清理缓存。手动启动时需先清理：rm -rf ~/Library/Caches/bun（macOS）或 rm -rf ~/.cache/bun（Linux） |
如果你想运行官方版本
npm install -g @anthropic-ai/claude-code技术栈
| 层次 | 技术 | |:---|:---| | 运行时 | Node.js >= 18, Bun >= 1.0 | | 语言 | TypeScript + React JSX | | UI | React 19，自定义终端渲染器，146+ 组件 | | CLI | Commander.js 12 | | AI/LLM | Anthropic SDK, Claude Agent SDK, OpenAI SDK, AWS Bedrock, Azure Identity | | 协议 | Model Context Protocol (MCP, 6 种传输), LSP, OAuth/XAA | | 可观测性 | OpenTelemetry (traces, metrics, logs) + OTLP 导出器 | | 代码工具 | ripgrep, Sharp (图片处理), Marked, Turndown, Diff |
项目结构
claude-code-source/
├── README.md # English documentation
├── README.zh.md # 本文档（中文）
├── assets/ # 图片资源
│ ├── anthropic-claude-code.webp
│ └── screenshot.png
├── package.json # 依赖声明（逆向工程）
├── tsconfig.json # TypeScript 配置
├── bunfig.toml # Bun preload 配置
├── preload.ts # 运行时 shim（feature flag、宏）
├── start.sh # 启动脚本
├── scripts/setup.mjs # 一键安装脚本
│
├── claude-code-deep-analysis/ # 18 篇原创分析文章（中文 + EN）
│ ├── README.md # 系列索引（中文）
│ ├── README.en.md # 系列索引（English）
│ ├── 00-core-conclusion.md # 每篇文章有 .md + .en.md
│ ├── 00-core-conclusion.en.md
│ ├── ...
│ └── 17-hook-system.en.md
│
└── src/ # Claude Code 源码（Anthropic）
├── query.ts # 核心 Agent 循环（1,729 行）
├── QueryEngine.ts # 会话管理（46.6 KB）
├── Tool.ts # 工具接口与注册（29.5 KB）
├── main.tsx # 主 React 组件（4,683 行）
│
├── entrypoints/ # 入口文件（CLI、MCP、SDK 类型）
├── commands/ # 87+ slash 命令
├── tools/ # 45+ 工具实现
│ ├── BashTool/ # Shell 执行（430 KB 安全代码）
│ ├── AgentTool/ # 子 Agent 执行
│ ├── FileEditTool/ # 文件编辑与 diff 匹配
│ ├── MCPTool/ # Model Context Protocol
│ └── ... # 30+ 更多工具
│
├── services/ # 38 个服务模块
│ ├── api/ # Anthropic API 集成
│ ├── mcp/ # MCP 协议（25 个子目录）
│ ├── compact/ # 上下文压缩
│ ├── SessionMemory/ # 跨会话记忆
│ └── ...
│
├── components/ # 146+ React UI 组件
├── hooks/ # 85+ React Hooks
├── utils/ # 564+ 工具函数
├── permissions/ # 权限系统（5 种模式）
├── bridge/ # CLI ↔ VS Code 集成
├── constants/ # System Prompt 组装与配置
├── memdir/ # 跨会话记忆系统
├── skills/ # Skill/插件系统
├── voice/ # 语音输入处理
└── ...版权声明
- 源代码：所有权利归 Anthropic, PBC 所有。不授予任何许可。
- 分析文章（
claude-code-deep-analysis/）：仓库维护者的原创评论和分析。代码片段仅用于教育目的。
联系方式：如有任何问题，请通过 GitHub Issues 联系。