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.
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.
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.
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 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.
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).
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.