Claude Code 从零实现 (Claude Code From Scratch)

一步一步，从零造一个 Claude Code

📘 在线阅读教程 →   |   📘 Read Tutorial (English) →   |   English

📖 想深入了解原理？ 姊妹项目 How Claude Code Works — 12 篇专题，33 万字，从源码级别深度解析 Claude Code 架构

---

Claude Code 开源了 50 万行 TypeScript。读不动？

本项目用 ~4300 行代码（TypeScript 和 Python 两个版本分别实现）复现了 Claude Code 的核心架构——Agent Loop、13 个工具（含并行执行 + 流式早期启动）、4 层上下文压缩、语义记忆召回、技能系统、多 Agent、MCP 集成……每一步都对照真实源码讲解“它怎么做的 → 我们怎么简化的”。

这不是 demo，是一份分步教程——13 章内容，跟着动手写几千行代码，快速理解 Claude Code 这样最好用的 coding agent 的精髓。读完你就理解了 coding agent 的工作原理，无需啃那几十万行代码。

📖 分步教程

13 章内容，分两个阶段——先构建一个可用的 Coding Agent，再逐步添加进阶能力。每章都贴真实代码 + Claude Code 源码对照：

章节	内容	对应源码
Phase 1: 构建一个可用的 Coding Agent
1. Agent Loop	核心循环：调用 LLM → 执行工具 → 重复	agent.ts ↔ query.ts
2. 工具系统	13 个工具 + mtime 防护 + 延迟加载	tools.ts ↔ Tool.ts + 66 工具
3. System Prompt	提示词工程 + @include 语法	prompt.ts ↔ prompts.ts
4. CLI 与会话	REPL、Ctrl+C、会话持久化	cli.ts ↔ cli.tsx
5. 流式输出	双后端 + 流式工具执行 + 并行执行	agent.ts ↔ api/claude.ts
6. 权限与安全	5 模式 + 声明式规则 + 危险检测	tools.ts ↔ permissions/ (52KB)
7. 上下文管理	4 层压缩 + 大结果持久化	agent.ts ↔ compact/
Phase 2: 进阶能力
8. 记忆系统	4 类型记忆 + 语义召回 + 异步预取	memory.ts ↔ memory.ts
9. 技能系统	技能发现 + inline/fork 双模式	skills.ts ↔ SkillTool/
10. Plan Mode	只读规划 + 4 选项审批工作流	agent.ts ↔ EnterPlanMode
11. 多 Agent	Sub-Agent fork-return 多 Agent 架构	subagent.ts ↔ AgentTool/
12. MCP 集成	JSON-RPC over stdio 连接外部工具	mcp.ts ↔ mcpClient.ts
13. 架构对比	完整对比 + 扩展方向	全局
14. 功能测试	19 项手动测试覆盖全部功能	test/

🚀 快速开始

TypeScript 版

git clone https://github.com/Windy3f3f3f3f/claude-code-from-scratch.git
cd claude-code-from-scratch
npm install && npm run build

Python 版（需要 Python 3.11+，详细说明）

cd python
pip install -e .
mini-claude-py          # 命令行入口（避免与 TS 版 mini-claude 冲突）
python -m mini_claude   # 或用 python -m 方式运行

配置 API

支持两种后端，通过环境变量自动识别：（支持自定义 base url）

方式一：Anthropic 格式（推荐）

export ANTHROPIC_API_KEY="sk-ant-xxx"
# 可选：使用代理
export ANTHROPIC_BASE_URL="https://aihubmix.com"

方式二：OpenAI 兼容格式

export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://api.openai