Skip to content

README_EN.md

Latest commit

 

History

History
95 lines (66 loc) · 4.31 KB

README_EN.md

File metadata and controls

95 lines (66 loc) · 4.31 KB
Raw

Mini Claude Code in Python

Dissect the core mechanisms of a coding agent — implement each module, compare across tools.

中文 · English

Python 3.11+ DeepSeek API Progress License: MIT

Start reading · Browse examples · Credits

Coding Agent demo

What this project does

A framework-free Python implementation of 11 core coding agent modules, each paired with design analysis documentation:

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 does a production coding agent need this layer? Where do long tasks break without it?
  2. How do messages flow? Data paths between model, harness, and tools.
  3. What's the minimal runnable implementation? Core path first, then production-level complexity.
  4. How do real tools differ here? Architecture comparison across Claude Code / Kimi Code / Codex.

Module overview

# Module Core mechanism Status
01 Agent Loop Multi-turn conversation, message history, thinking block filtering ✅
02 Tool Use Tool calling, result passback, two-layer agent loop ✅
03 System Prompt Static rules, runtime context, CLAUDE.md project instructions ✅
04 CLI & Session Async agent, REPL commands, session save & resume ✅
05 Streaming Streaming output, spinner, transient error retry ✅
06 Permissions Dangerous command detection, user confirmation, session allowlist ✅
07 Context Engineering 4-layer compression: truncate → budget → dedup → LLM summary ✅
08 Memory Filesystem memory, MEMORY.md index, cross-session persistence ✅
09 Skills Skill discovery, system prompt injection, slash commands ✅
10 Plan Mode Read-only exploration, active plan file, permission blocking ✅
11 Sub-Agent Restricted toolset, output buffer, parent-child context isolation ✅
12 MCP External tool server connection Planned

Scale

  • 11,000+ lines of implementation code (11 modules, each independently runnable)
  • 7,500+ lines of design analysis documentation
  • 13 version tags — one traceable milestone per module

Low-cost API

The code uses the Anthropic Python SDK. DeepSeek's Anthropic-compatible endpoint lets you run everything without a Claude API key.

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 keys are read from environment variables. Never commit real keys to code or Git history.

Who this is for

  • Developers using Claude Code / Kimi Code / Cursor who want to understand what's underneath
  • Engineers building coding agents without framework abstraction
  • Anyone preparing for AI Agent roles who needs depth on Agent Loop / Tool Use / Context Engineering

Credits

Inspired by claude-code-from-scratch by @Windy3f3f3f3f. This repository reorganizes the learning path, adds independent design analysis and cross-tool comparison. Thanks to the original contributors.

License

MIT