Mini Claude Code Python

Mini Claude Code in Python

逐模块拆解 Coding Agent 核心机制，独立实现，逐层对比。

[中文](./README.md) · [English](./README_EN.md)

[](https://www.python.org/) [](https://api-docs.deepseek.com/guides/anthropic_api) [](./chapters/11-sub-agent.md) [](./LICENSE)

[开始阅读](./chapters/01-agent-loop.md) · [查看参考代码](./examples/) · [致谢](#致谢)

---

这个项目做了什么

不依赖 LangChain / LangGraph 等框架，用 Python 独立实现 Coding Agent 的 11 个核心模块，每个模块配套设计分析文档：

Agent Loop → Tool Use → System Prompt → CLI & Session → Streaming
→ Permissions → Context Engineering → Memory → Skills → Plan Mode → Sub-Agent

每个模块回答四件事：

1. 生产级 Coding Agent 为什么需要这一层：缺少它时，长任务会在哪里失效？
2. 消息怎么流动：模型、Harness 和工具之间的数据流。
3. 最小可运行实现：先跑通核心路径，再理解生产级复杂度。
4. 设计决策对比：Claude Code / Kimi Code / Codex 在这一层的架构差异。

模块总览

| # | 模块 | 核心机制 | 状态 | |---|------|---------|:---:| | 01 | [Agent Loop](./chapters/01-agent-loop.md) | 多轮对话、消息历史、thinking block 过滤 | ✅ | | 02 | [Tool Use](./chapters/02-tools.md) | 工具调用、结果回传、两层 Agent Loop | ✅ | | 03 | [System Prompt](./chapters/03-system-prompt.md) | 静态规则、运行时上下文、CLAUDE.md 项目指令 | ✅ | | 04 | [CLI & Session](./chapters/04-cli-session.md) | async Agent、REPL 命令、会话保存与恢复 | ✅ | | 05 | [Streaming](./chapters/05-streaming.md) | 流式输出、spinner、transient error 重试 | ✅ | | 06 | [Permissions](./chapters/06-permissions.md) | 危险命令检测、用户确认、会话内白名单 | ✅ | | 07 | [Context Engineering](./chapters/07-context.md) | 4 层分级压缩：截断 → Budget → 去重 → LLM 摘要 | ✅ | | 08 | [Memory](./chapters/08-memory.md) | 文件系统记忆、MEMORY.md 索引、跨会话持久化 | ✅ | | 09 | [Skills](./chapters/09-skills.md) | 技能发现、system prompt 注入、斜杠命令 | ✅ | | 10 | [Plan Mode](./chapters/10-plan-mode.md) | 只读探索、active plan 文件、权限拦截 | ✅ | | 11 | [Sub-Agent](./chapters/11-sub-agent.md) | 受限工具集、输出 buffer、父子上下文隔离 | ✅ | | 12 | MCP | 外部工具服务器连接 | 计划中 |

项目规模

• 11,000+ 行实现代码（11 个模块，逐章独立可运行）
• 7,500+ 行设计分析文档
• 13 个版本 tag，每个模块一个可回溯的里程碑

低成本运行

代码使用 Anthropic Python SDK，通过 DeepSeek 的 Anthropic 兼容接口即可运行，无需购买 Claude API。

git clone https://github.com/Xiaxia1997/mini-claude-code-python.git
cd mini-claude-code-python

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

export DEEPSEEK_API_KEY="your-api-key"
cd examples/chapter-11
python agent.py

> [!IMPORTANT] > 代码通过环境变量读取 API Key，不要把真实密钥写进代码或 Git 历史。

适合谁

• 正在使用 Claude Code / Kimi Code / Cursor，想理解底层机制的开发者
• 想从零搭建 Coding Agent，不想被框架抽象淹没的人
• 准备 AI Agent 相关岗位面试，需要深入理解 Agent Loop / Tool Use / Context Engineering 的求职者

致谢

本项目的学习路径受到 claude-code-from-scratch 启发。在实践过程中重新组织了讲解结构，并加入了独立的设计分析和跨工具对比。感谢 @Windy3f3f3f3f 及原项目贡献者的开源工作。

License

[MIT](./LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Xiaxia1997
• Source: Xiaxia1997/mini-claude-code-python
• License: MIT

Install and usage instructions live in the source repository linked above.