mini-claude-code-python

<div align="center"> # Mini Claude Code in Python **Deconstructing and independently implementing the core mechanisms of Coding Agent, layer by layer for comparison.** [English](./README_EN.md) [](https://www.python.org/) [](https://api-docs.deepseek.com/guides/anthropic_api) [](./chapters/11-sub-agent.md) [](./LICENSE) [Get Started](./chapters/01-agent-loop.md) · [Reference Code](./examples/) · [Acknowledgments](#acknowledgments)  </div> --- ## What This Project Does This project independently implements 11 core modules of Coding Agent using Python, without relying on frameworks like LangChain or LangGraph. Each module comes with a design analysis document: ```text Agent Loop → Tool Use → System Prompt → CLI & Session → Streaming → Permissions → Context Engineering → Memory → Skills → Plan Mode → Sub-Agent ``` Each module answers four questions: 1. **Why is this layer necessary for a production-grade Coding Agent?** What would happen if it's missing? 2. **How do messages flow?** Data flow between the model, harness, and tools. 3. **Minimal runnable implementation**: Get the core path working before understanding production-grade complexity. 4. **Design decision comparisons**: Architectural differences between Claude Code, Kimi Code, and Codex. ## Module Overview | # | Module | Core Mechanism | Status | |---|------|---------|:---:| | 01 | [Agent Loop](./chapters/01-agent-loop.md) | Multi-turn dialogue, message history, thinking block filtering | ✅ | | 02 | [Tool Use](./chapters/02-tools.md) | Tool invocation, result transmission, two-layer Agent Loop | ✅ | | 03 | [System Prompt](./chapters/03-system-prompt.md) | Static rules, runtime context, `CLAUDE.md` project instructions | ✅ | | 04 | [CLI & Session](./chapters/04-cli-session.md) | Async Agent, REPL commands, session saving and restoration | ✅ | | 05 | [Streaming](./chapters/05-streaming.md) | Streaming output, spinner, transient error retry | ✅ | | 06 | [Permissions](./chapters/06-permissions.md) | Dangerous command detection, user confirmation, session whitelist | ✅ | | 07 | [Context Engineering](./chapters/07-context.md) | 4-layer hierarchical compression: truncation → budget → deduplication → LLM summarization | ✅ | | 08 | [Memory](./chapters/08-memory.md) | File system memory, `MEMORY.md` index, cross-session persistence | ✅ | | 09 | [Skills](./chapters/09-skills.md) | Skill discovery, system prompt injection, slash commands | ✅ | | 10 | [Plan Mode](./chapters/10-plan-mode.md) | Read-only exploration, active plan file, permission interception | ✅ | | 11 | [Sub-Agent](./chapters/11-sub-agent.md) | Restricted toolset, output buffer, parent-child context isolation | ✅ | | 12 | MCP | External tool server connection | Planned | ## Project Scale - **11,000+** lines of implementation code (11 modules, each chapter independently runnable) - **7,500+** lines of design analysis documents - **13** version tags, each module with a traceable milestone ## Low-Cost Operation The code uses the Anthropic Python SDK and can run through DeepSeek's Anthropic-compatible interface without purchasing the Claude API. ```bash 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] > The code reads the API Key through environment variables. Do not write the actual key into the code or Git history. ## Suitable Audience - Developers using Claude Code, Kimi Code, or Cursor who want to understand the underlying mechanisms. - Those who want to build a Coding Agent from scratch without being overwhelmed by framework abstractions. - Job seekers preparing for AI Agent-related interviews who need to deeply understand Agent Loop, Tool Use, and Context Engineering. ## Acknowledgments The learning path of this project was inspired by [claude-code-from-scratch](https://github.com/Windy3f3f3f3f/claude-code-from-scratch). The explanation structure was reorganized, and independent design analysis and cross-tool comparisons were added. Thanks to [@Windy3f3f3f3f](https://github.com/Windy3f3f3f3f) and the original project contributors for their open-source work. ## License [MIT](./LICENSE)