Claude Code From Scratch
Reimplement Claude Code's core in ~5,000 lines of code with a 13-chapter step-by-step tutorial to understand Coding Agents.
- Source repo
- Windy3f3f3f3f/claude-code-from-scratch
- Stars
- ★ 2.8k
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 60/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want to deeply understand Claude Code's inner workings but find the 500k-line codebase overwhelming, using a step-by-step tutorial to reimplement the core.
- Not a fit if
- Teams needing production-grade robustness; this is a teaching minimal implementation
- Source review
- 60/100 · Some gaps
What does this agent do, and when should you use it?
This is an educational project that reimplements the core architecture of Claude Code from scratch in about 5,000 lines of TypeScript or Python, rather than a full replacement. It includes a 13-chapter tutorial covering the Agent Loop, 13 tools (including parallel execution and streaming early start), 4-layer context compaction, semantic memory recall, skill system, multi-agent collaboration, and MCP integration. Each chapter's code is runnable without an API key, powered by a local mock model, with '--diff' to see newly added code. The project offers two functionally equivalent versions in TypeScript and Python, supports Anthropic and OpenAI-compatible API backends, and includes detailed architecture comparisons with Claude Code.
The project provides a complete implementation and tutorial for building a Coding Agent from scratch. The core is an Agent Loop: repeatedly calling the LLM, executing tools, and processing results until the task is complete. It implements 13 tools (e.g., file read/write, Shell, WebFetch, ToolSearch), supporting parallel execution of read-only tools and streaming output. It includes 4-layer context compaction, 5 permission modes, 4 memory types with semantic recall and async prefetch, a skill system (inline/fork modes), Sub-Agent multi-agent architecture, and an MCP client. It provides an interactive REPL CLI, session persistence, budget control (--max-cost, --max-turns), cross-platform shell auto-detection, and error retries. Each chapter includes a runnable minimal implementation, demonstrated via node steps/run.mjs <N> without needing real APIs.
- Developers who want to deeply understand Claude Code's inner workings but find the 500k-line codebase overwhelming, using a step-by-step tutorial to reimplement the core.
- Learners who want hands-on experience with Coding Agents, using runnable minimal code to quickly validate concepts without API keys.
- Technical instructors or bloggers needing a structured, reproducible teaching resource for topics like Agent Loop, tool systems, and context management.
- Developers who want to integrate a lightweight Coding Agent core into their own projects, using this as a reference or base.
- Researchers interested in advanced features like multi-agent collaboration and MCP integration, referencing the implementation patterns.
How do you install or deploy this agent?
Clone the repository: git clone https://github.com/Windy3f3f3f3f/claude-code-from-scratch.git, then cd claude-code-from-scratch and run npm install && npm run build. For Python version (requires Python 3.11+), cd python && pip install -e .. Configure API by setting environment variables: ANTHROPIC_API_KEY (Anthropic format) or OPENAI_API_KEY and OPENAI_BASE_URL (OpenAI-compatible format).
How do you use this agent?
Run the TypeScript version: npm start for interactive REPL mode, with flags like --resume to resume last session, --yolo to skip safety confirmations, --plan for plan mode, --max-cost for spending limits. Python version uses mini-claude-py command. In-session commands include /clear, /cost, /compact, /memory, /skills. To run tutorial chapters: node steps/run.mjs <N> where N is chapter number; use --diff to see code changes, --py for Python version, --live to connect to real models.
What are this agent's strengths and limitations?
- Every chapter's code runs without an API key, using a local mock model, making it easy to learn and debug.
- Provides both TypeScript and Python versions to suit different language preferences.
- Detailed architecture comparison tables clearly show differences from Claude Code.
- Educational nature; feature completeness and robustness are not production-grade compared to Claude Code.
- Default model
claude-opus-4-6may require a valid API key, and there is no built-in model fallback strategy. - Advanced features like context compaction are simplified implementations that may differ from the original behavior.
How does this agent compare with similar options?
Compared to Claude Code, this project is positioned as a learning minimal implementation: only 13 tools (vs. 66+ in Claude Code), ~5000 lines of code (vs. 500k+), simplified permission system (5 modes vs. 7-layer + AST), and multi-agent only supports Sub-Agent (vs. Coordinator + Swarm).
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claude Code From Scratch This agent | 60 · Some gaps | CLIFree + model costs | ★ 2.8k | 3mo ago | Python | OpenAI API · Claude API |
| PI from Scratch | 56 · Major gaps | CLIFree + model costs | ★ 1.3k | 2mo ago | TypeScript | OpenAI API |
| Learn Claude Code: Harness Engineering for Real Agents | 48 · Major gaps | CLIFree + model costs | ★ 79k | 20d ago | Python | Claude API |
| Donggua's AI Learning Notes: In-depth Pi-Agent SDK Tutorial | 23 · Major gaps | Web appFree | ★ 3.4k | 1mo ago | MDX | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows permission modes (5 modes + declarative rules + dangerous command detection), but no detailed least-privilege principle; user confirmation mechanisms exist (--dont-ask, --accept-edits), but not all dangerous operations are explicitly confirmed; data flow transparency insufficient, no explanation of API key and conversation data flow; sensitive data handling not explicit; dependency security not audited; external effects controlled (budget limits, turn limits), but rollback mechanism not described; source attribution has contributor list and disclaimer, but not verified.
Self-consistency good, README matches code structure, tests present; dependency availability has package.json and Python deps, but not verified; failure messages have error recovery (exponential backoff), but not detailed.
Audience clear (developers learning Claude Code), scenarios clear (step-by-step tutorial); capability boundaries have comparison table; trigger precision has CLI args and REPL commands; environment fit has cross-platform notes.
Information architecture clear (directory structure, architecture diagram); install notes detailed; naming stable (mini-claude); examples and FAQ present (tutorial); known limitations have comparison table; license MIT; version number in package.json, but no CHANGELOG; maintenance responsibility has contributor list.
Output usability high (tutorial + runnable code); marginal value high (learning project); cost-benefit good (runs without API key).
Claims traceable (tutorial matches code); cross-source corroboration (TS and Python versions); fact-inference separation (disclaimer not guaranteeing consistency with Claude Code).
- Dependency security not verified, recommend auditing dependencies.
- Data flow transparency insufficient, need to clarify handling of API keys and conversation data.
- Rollback mechanism not described, recommend adding.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
FAQ
Do I need an API key to run the tutorial chapters?
--live flag to connect to real APIs.Which model backends are supported?
Is this project affiliated with Anthropic?
How to customize the model?
MINI_CLAUDE_MODEL or pass --model as a command-line argument (CLI takes precedence).Is there a Python version?
mini-claude-py command.