Claude Code From Scratch: A 5,000-Line Tutorial That Rebuilds a Coding Agent

Why rebuild Claude Code from scratch

Claude Code is a large, closed-source coding agent. Its internal implementation is hard to read, and the README says it has hundreds of thousands of lines. This project targets developers who want to understand how such an agent works without reading all of that. It offers a 13-chapter tutorial that builds a simplified version, called Mini Claude Code, in about 5,000 lines of code. The two implementations, one in TypeScript and one in Python, are written separately but cover the same features. The intended audience is someone who learns by doing, not someone who needs a ready-made tool. The README positions the project as a study aid, not a product.

The architecture you will build

The tutorial is split into two phases. Phase 1 constructs a working coding agent: the agent loop, a tool system with 13 tools, system prompt handling with @include syntax, a CLI with REPL and session persistence, streaming output with two backends, permission modes, and context management with four layers of compression. Phase 2 adds memory, skills, plan mode, multi-agent support, and MCP integration. Each chapter maps a component to its counterpart in Claude Code, such as agent.ts versus query.ts, and tools.ts versus Tool.ts. The README gives a concrete example of the agent loop: call the LLM, execute tools, repeat. This is the core mechanism that everything else hangs on.

Every chapter runs without an API key

A distinctive feature is that each code chapter ships with a minimal implementation that runs with a single command. The README shows the command format: node steps/run.mjs --list lists runnable chapters, node steps/run.mjs 7 runs chapter 7, and adding --py switches to the Python version. The output is generated by a local mock model, so it does not require network access or an API key. The --diff flag shows only the lines added in that chapter compared to the previous one. This design lets a reader see the incremental growth of the codebase. The README claims that the code in each chapter, the code blocks in the documentation, and the output shown are all generated from the same source, which aims to prevent the common problem of documentation drifting from actual code.

Getting it running: commands and configuration

For the TypeScript version, the quick start is git clone, npm install, and npm run build. The Python version requires Python 3.11 or later, and you install it with pip install -e . inside the python directory. The command line entry point is mini-claude-py, which avoids a name conflict with the TypeScript version's mini-claude. Both versions support two API backends, selected by environment variables. The Anthropic format uses ANTHROPIC_API_KEY and optionally ANTHROPIC_BASE_URL for a proxy. The OpenAI-compatible format uses OPENAI_API_KEY and OPENAI_BASE_URL. The default model is claude-opus-4-6, but you can override it with the MINI_CLAUDE_MODEL environment variable or a --model command line argument. The Python version can also be run as python -m mini_claude.

CLI options and REPL commands

The runtime offers several flags that mirror common agent behaviors. npm start launches an interactive REPL, --resume restores the last session, --yolo skips safety confirmations and auto-executes dangerous commands, --plan runs in read-only plan mode, --accept-edits auto-approves file edits, --dont-ask rejects operations that need confirmation, and --max-cost sets a dollar limit. There is also --max-turns to cap the number of turns. Inside the REPL, slash commands provide control: /clear resets history, /cost shows token usage and cost estimates, /compact manually triggers context compression, /memory lists saved memories, and /skills lists available skills. You can invoke a specific skill with /<skill>, such as /commit. These options give a practical sense of how a coding agent manages permissions and cost, which is useful for understanding the trade-offs in real agents.

Where the project falls short

The README is explicit that this is not an exact replica. It says the project follows Claude Code's publicly observable behavior and general agent patterns, but it does not guarantee consistency with the real internal implementation. That is a genuine limitation. If you need to debug a specific issue in Claude Code or rely on its exact behavior, this tutorial will not help. Another limitation is the scale: 13 tools versus the 66 tools mentioned in the comparison table, and 5,000 lines versus hundreds of thousands. The tutorial necessarily omits many edge cases and production hardening. The mock model is useful for learning, but it cannot reveal how a real LLM behaves in ambiguous situations. The README also notes that the project is not affiliated with Anthropic, and Claude Code is a trademark of Anthropic, which matters if you plan to use the name in your own work.

A real alternative: reading the original source

The obvious alternative is to read Claude Code's actual source code, but that is exactly what this project tries to avoid. The README mentions a sister project, How Claude Code Works, which offers 12 articles and 330,000 words of source-level analysis. That project takes a different approach: instead of rebuilding from scratch, it explains the existing architecture in depth. If you prefer to understand the real system without reimplementing it, that might be a better fit. The trade-off is that you still have to deal with the complexity of the original code, but you get accuracy. This project trades accuracy for accessibility, giving you a simplified model that is easier to grasp but not guaranteed to match reality.

Maintenance and licensing

The repository is licensed under MIT, which allows free use, modification, and distribution with attribution. The last push was on July 9, 2026, and the latest release is v1.0.0 from March 31, 2026, so the project appears to be actively maintained, at least as of that date. The README does not discuss upgrade paths or long-term maintenance commitments. The tutorial structure, with chapters that build on each other, implies that updating one part could require updating others. The Python and TypeScript versions are separate, so changes to one do not automatically apply to the other, which could increase maintenance effort if you contribute. The dependency on a mock model and the specific API formats means that breaking changes in Anthropic or OpenAI APIs could affect the live mode, though the mock mode should remain stable.

Editorial conclusion

Adopt this if you are a developer who learns by reading and modifying code, especially if you want to understand coding agents without wading through Claude Code's hundreds of thousands of lines. Skip it if you need a production tool or an exact clone of Claude Code, since the README explicitly disclaims internal fidelity. Before relying on it, verify that the tutorial's architecture matches your mental model, check the current state of the code against the last push date, and confirm that the mock model behavior aligns with what you expect from a real LLM. The project is a learning artifact, not a drop-in replacement, so treat its claims as pedagogical rather than authoritative.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Windy3f3f3f3f/claude-code-from-scratch on GitHub