# claude-code-from-scratch: a 5000-line rebuild of a coding agent, chapter by chapter > Windy3f3f3f3f's MIT-licensed tutorial reconstructs the core of Claude Code in TypeScript and Python, with runnable chapter code that needs no API key. It teaches architecture, not parity. **Windy3f3f3f3f/claude-code-from-scratch** — Build your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓 - Repository: https://github.com/Windy3f3f3f3f/claude-code-from-scratch - Website: https://windy3f3f3f3f.github.io/claude-code-from-scratch/#/ - Stars: 2,720 · Forks: 548 - Language: Python - License: MIT - Published: 2026-09-09 · Updated: 2026-09-09 · Language: en - Canonical page: https://hysenlabs.com/projects/windy3f3f3f3f-claude-code-from-scratch ## What claude-code-from-scratch is actually for Claude Code ships as a large, closed codebase. The README opens with the problem in one line: the code is hundreds of thousands of lines and hard to read through. This project answers that with a rebuild of roughly 5000 lines, written twice, once in TypeScript and once in Python, and split into 14 documented chapters. The audience is narrow and specific. It is for engineers who want to understand how an agent loop, a tool registry, a permission layer and a context compressor fit together, and who learn better by writing the code than by reading a blog post. The README is explicit that this is a tutorial, not a demo, and the disclaimer at the top is worth reading before anything else: the project follows Claude Code's publicly observable behaviour and general agent patterns, and does not guarantee consistency with the real internal implementation. It also states that Claude Code is an Anthropic trademark and that the project is unaffiliated with Anthropic. Treat it as a teaching artifact, not as a specification. A sister project, how-claude-code-works, is linked for readers who want source-level analysis instead of a rebuild. ## The agent loop and the 13 tools behind it Chapter 1 is the smallest useful thing: call the model, execute a tool, feed the result back, repeat. The README maps agent.ts in the tutorial against query.ts in Claude Code, which tells you the intended shape of the comparison even though the two files are not the same code. Chapter 2 is where the design gets opinionated. The tutorial implements 13 tools, with two mechanisms that are easy to get wrong in a hand-written agent: an mtime guard and lazy loading. The mtime guard is a staleness check, so a tool that reads or edits a file can notice the file changed underneath it. Lazy loading keeps tool definitions out of the prompt until they are needed. The README contrasts this with Claude Code's Tool.ts and its 66 tools, which is the honest framing: the tutorial covers the mechanism, not the catalogue. Parallel execution and streaming early start appear in chapter 5, described as a second backend plus streaming tool execution. Early start means a tool can begin before the model has finished emitting its full response. That is a real architectural decision with real failure modes, and it is the kind of detail that justifies reading a rebuild instead of a summary. ## Running a chapter without an API key The most practical design choice here is the per-chapter runner. Each code chapter has a minimal implementation that runs with one command against a local mock model, so you can watch the mechanism work before you wire up credentials. The README states that the code in each chapter, the code blocks in the documentation, and the printed output are all generated from the same source, which is the project's answer to documentation that drifts from code. Start by listing what is runnable: ```bash node steps/run.mjs --list ``` You should see the chapter numbers the runner can execute. Then run one and read its output: ```bash node steps/run.mjs 7 node steps/run.mjs 7 --diff node steps/run.mjs 7 --py ``` Chapter 7 is context management, so the expected output is a conversation that has grown long and then has older messages compressed into a summary. The --diff flag prints only the lines that chapter adds relative to the previous one, and --py switches to the Python implementation. The --live flag, per the README, points the same chapter at a real model using your own prompt. For the full CLI, the TypeScript path is a clone, install and build, then npm start for the REPL. The Python path lives under python/ and requires Python 3.11 or newer. Note the entry point names: mini-claude for the TypeScript binary and mini-claude-py for Python, which the README says avoids a collision between the two. ## Context compression, memory and the parts that are approximated Four layers of context compression are implemented in chapter 7, alongside persistence of large tool results. Chapter 8 adds four memory types with semantic recall and asynchronous prefetching, mapped against Claude Code's memory.ts. Chapter 11 covers sub-agents in a fork-return architecture, and chapter 12 connects external tools over JSON-RPC on stdio for MCP. The honest limitation sits in the README's own comparison table and disclaimer. The tutorial's permission layer is a chapter; Claude Code's permissions directory is listed at 52KB. The tutorial's tool system is 13 tools; Claude Code's is 66. Those gaps are not defects in a teaching project, but they mean you cannot reason about Claude Code's security posture from this code. The five permission modes, declarative rules and dangerous-command detection are described as a simplified model. If your goal is to audit how a production agent decides what to execute, this rebuild gives you the vocabulary and not the answer. The second limitation is language parity. Two implementations exist, and package.json carries a test:integration:py script specifically for Python parity checks, which implies parity is something the project tests rather than assumes. Whether the Python version lags behind on a given chapter is something the runner will show you faster than the README will. ## How this differs from reading Claude Code or using it The obvious alternative is reading Claude Code itself, and the project's premise is that this does not scale: hundreds of thousands of lines with no guided path. The second alternative is simply using Claude Code, which is a different activity entirely. Claude Code is a finished product you install and run; this repository is a curriculum you work through. Choosing between them is a question of whether you want a working agent today or an understanding of one. A third comparison is the sister project, how-claude-code-works, which the README describes as 12 articles and roughly 330,000 characters of source-level analysis of Claude Code's architecture. That is the reading-first path. claude-code-from-scratch is the writing-first path: the same territory approached by building a smaller version and comparing each piece as you go. If you bounce off long architecture write-ups, the chapter runner is the difference that matters, because you can execute the concept instead of only reading about it. ## Licence, maintenance and what an upgrade costs you The licence is MIT, per the LICENSE file and the badge in the README. That permits reuse and modification with attribution and without warranty, which is the usual arrangement for a tutorial codebase. It does not grant any rights to Claude Code itself, and the README's trademark note makes clear the project is not affiliated with Anthropic. If you plan to lift code from the chapters into something you ship, the MIT terms are the ones that apply to this repository, and nothing here speaks to Anthropic's terms for their product. The last push to the default branch was on 2026-07-09, and the repository is not archived. The only release is v1.0.0 from 2026-03-31. There is no published deprecation notice and no stated support window in the repository, so treat the version number as a snapshot rather than a compatibility promise. Upgrading is not a package-manager operation in the usual sense: you clone and rebuild, and the chapters are the interface. The scripts that matter for keeping a fork honest are steps:docs:check, which verifies documentation is in sync, and steps:ci, which chains the marker lint, the mock-model self-tests in both languages, the step tests and the docs check. Running those after you modify a chapter tells you whether you broke the generated-code contract. ## Conclusion Adopt it if you want to read and run the internals of a coding agent rather than guess at them, and if you are comfortable that the target is Claude Code's observable behaviour, not its source. Skip it if you need a production CLI, a drop-in Claude Code replacement, or an agent whose internals are documented as matching the original. Before committing, run node steps/run.mjs --list to confirm the chapter you care about is runnable, then node steps/run.mjs 7 --diff to see how much code a single chapter actually adds. The repository's own disclaimer settles the rest: it does not guarantee consistency with Claude Code's real internal implementation. ## FAQ ### What does Claude Code actually do? The README describes Claude Code as a coding agent with an agent loop, a large tool set, permissions, context compression, memory, skills and MCP integration. This project rebuilds those mechanisms in about 5000 lines so you can read them rather than infer them from the product. ### How to build your own claude code? Follow the 14-chapter tutorial, starting with the agent loop in chapter 1 and adding the tool system, system prompt, CLI, streaming, permissions and context management. Each code chapter runs with node steps/run.mjs against a local mock model, so no API key is required while you learn the structure. ### Can Claude Code build an app from scratch? The README does not claim that, and this project is a rebuild of a coding agent rather than an app generator. What the README does state is that the tutorial's tools include file editing and that the CLI exposes a plan mode which analyzes without modifying anything. ## Sources - [License: MIT](https://github.com/Windy3f3f3f3f/claude-code-from-scratch/blob/main/LICENSE) - [Project website](https://windy3f3f3f3f.github.io/claude-code-from-scratch/#/) - [README](https://github.com/Windy3f3f3f3f/claude-code-from-scratch/blob/main/README.md) - [Releases](https://github.com/Windy3f3f3f3f/claude-code-from-scratch/releases) - [Windy3f3f3f3f/claude-code-from-scratch on GitHub](https://github.com/Windy3f3f3f3f/claude-code-from-scratch) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/windy3f3f3f3f-claude-code-from-scratch