claude-code-from-scratch counts its chapters three ways and its lines two ways
Build your own Claude Code from scratch. Claude Code's 500k-line codebase too much to read? Recreate its core architecture in about 5000 lines of TypeScript/Python, with an 11-chapter step-by-step tutorial to understand the essence of coding agents.
At a glance
- What is it?
- This repository rebuilds a small coding agent in TypeScript with a Python port, in thirteen chapters that each run against a local mock model. The page around that code disagrees with itself in three places worth knowing before you start: how many chapters there are, how many lines of code they add up to, and which language the project is written in.
- Who is it for?
- Read this project as a tutorial with an unusually complete test setup, not as a drop in replacement for Claude Code, and its own disclaimer says as much: it is built from publicly observable behaviour and makes no claim about matching the real internals, and Claude Code is a trademark of Anthropic. Before you rely on it, check three things.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- Windy3f3f3f3f/claude-code-from-scratch2,832 ★ · +165
| Repository | 2026-09-10 | 2026-11-13 |
|---|---|---|
| Windy3f3f3f3f/claude-code-from-scratch | 2.7k | 2.8k |
165 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The page counts its own chapters three different ways
Three numbers appear within one repository. The description says 11 chapters. The tutorial section says 13 chapters split into two phases. The table under it numbers fourteen rows, and its final row is not a build chapter at all but a testing chapter covering 22 manual tests across all features.
Chapters 1 through 13 are the code chapters: agent loop, tools, system prompt, CLI and session, streaming, permissions, context management, then memory, skills, plan mode, multi agent, MCP integration and an architecture comparison. Each row names the file in this project and the file it is being compared against in Claude Code, so chapter 2 reads `tools.ts` against `Tool.ts` plus 66 tools, and chapter 6 reads `tools.ts` against a `permissions/` directory the page measures at 52KB.
The discrepancy is not a rounding difference between counting conventions. Eleven, thirteen and fourteen are three different counts of the same table, and a reader who follows the description's number finishes two chapters early without being told anything was skipped.
The line count in the description and in package.json differ by two thousand
The description claims about 5000 lines, written twice over as separate TypeScript and Python versions. The package manifest describes the same project as built from scratch in about 3000 lines.
Both numbers are in files a reader sees on the first visit, and neither is broken down. There is no count for the TypeScript tree alone, none for the Python tree alone, and no statement of whether tests, the steps runner or the documentation site count toward the total. The tree does make the shape visible: a `src/` directory for the TypeScript build, a `python/` directory for the port, a `steps/` directory holding the per chapter runner, and a `docs/` directory beside them.
For a project whose selling point is that the whole thing is small enough to read, the headline size is the first number a reader would put in a citation, and the repository gives two.
Every chapter runs against a local mock, and --live is the only door to a real model
The part of this repository that is unusual is that the tutorial is executable. Each code chapter has a minimal implementation that runs on its own:
node steps/run.mjs --list # 列出所有能跑的章节
node steps/run.mjs 7 # 跑第 7 章:对话变长了,它把旧消息压成摘要
node steps/run.mjs 7 --diff # 只看这一章比上一章多写的那几行
node steps/run.mjs 7 --py # 换成 Python 版The output comes from a local mock model and does not touch the network, and `--diff` shows only the lines that chapter adds over the previous one. Connecting your own prompt to a real model takes the `--live` flag.
The claim that the code in the chapter, the code block in the documentation and the output you see all come from one source is enforced rather than asserted. The manifest carries `steps:docs` running `node steps/docs-sync.mjs` and `steps:docs:check` running the same script with `--check`, and both are folded into the `steps:ci` chain that runs before anything is considered done.
--yolo, --accept-edits and --dont-ask answer the same question three ways
Five permission modes sit behind five flags, and they do not form a single spectrum of caution. The default can prompt for actions requiring confirmation, subject to the configured rules. `--plan` is read only and analyses without modifying. `--accept-edits` approves file edits automatically. `--yolo` skips safety confirmation entirely, so dangerous commands execute as they come. `--dont-ask` is the CI mode and answers the other way: anything that would require a confirmation is refused automatically.
That last pair is the part worth reading twice, because the two flags look like neighbours and behave as opposites. One assumes yes, the other assumes no, and both take the decision away from whoever is sitting at the terminal. The Python port exposes the same five flags under the same names on `mini-claude-py`.
The comparison against the real thing is explicit about the gap. Claude Code is described as having seven layers with AST analysis; this implementation is described as five modes with declarative rules and regular expression detection. The edit verification story is similarly compressed, from a 14 step pipeline down to quote tolerance, uniqueness checking, an mtime guard and diff output.
Two backends, one environment switch, and a relay host in the example
The backend is chosen by environment variable, and both shapes are supported. The Anthropic format is the recommended one, taking `ANTHROPIC_API_KEY` and an optional `ANTHROPIC_BASE_URL`. The OpenAI compatible format takes `OPENAI_API_KEY` and `OPENAI_BASE_URL`. A custom base URL is supported for both, which is what makes relays usable.
The default model is `claude-opus-4-6`, overridable through `MINI_CLAUDE_MODEL` or through a command line argument, with the argument taking priority. The page's own example of that argument points a Claude Code rebuild at `gpt-4o`.
Two details deserve attention. The base URL example given for the recommended path is a third party relay host rather than an Anthropic endpoint, while the `.env.example` file in the repository root defaults to `https://api.anthropic.com`. And the cost controls are per run rather than per month: `--max-cost 0.50` in dollars and `--max-turns 20`, with `/cost` in the REPL reporting accumulated token use and an estimate. Reading a value out of a relay URL before pasting a key into that same environment is worth doing.
The Python half of the check suite assumes a virtualenv at a fixed path
The manifest wires a long chain of checks, and one link has a hardcoded path in it. `steps:selftest:py` runs `.venv/bin/python steps/mock_anthropic.selftest.py`, and `steps:ci` calls that same `.venv/bin/python` again before running the mock self test, the chapter tests, the self check and the documentation sync. On a machine where the Python port was installed somewhere else, that chain fails on the first link rather than skipping it.
The rest of the suite is broader than the documentation admits. `npm test` runs `test:unit` and `test:integration`. `test:unit` deletes a `dist-test` directory, compiles with `tsconfig.test.json` and runs node's own test runner over the compiled output. `check` adds `test:py`, which is a unittest discovery run over `python/tests`. `check:full` adds `test:integration:py`, a parity test that compares the two implementations. A separate `test:live` target exists for the tests that need a real model.
So the page advertises 22 manual tests covering all features, and the manifest ships a unit, integration, parity and live suite. The manual count is the smaller half of what is here.
A repository about MCP ships its own .mcp.json, .claude/ and CLAUDE.md
Chapter 12 covers MCP integration through JSON-RPC over stdio, with a class called McpManager set against Claude Code's `mcpClient.ts` plus dynamic tool discovery. The root of the repository then carries its own MCP configuration in `.mcp.json`, an agent configuration directory in `.claude/`, and a `CLAUDE.md` at the top level.
That is not incidental packaging. The manifest declares `"type": "module"` and points its binary at `./dist/cli.js`, so the `mini-claude` entry point exists only after `tsc` has run, which is why the quick start pairs `npm install` with `npm run build` before anything is runnable. The Python side is a separate distribution in `python/`, installed editable, with the console script named `mini-claude-py` specifically so it does not collide with the TypeScript build's `mini-claude`.
The documentation site is in the same tree as well. `index.html`, `_sidebar.md`, `_coverpage.md`, a `docs/` directory, an `en/` directory, `demo.mp4` and a `.nojekyll` file are all tracked at the root, which is what makes the repository's homepage field a rendered site rather than a landing page.
The repository is filed under Python while its build is TypeScript
The repository's primary language is recorded as Python. Everything structural in the tree points the other way: the package manifest is a Node module, the build script is `tsc`, the CLI target is `dist/cli.js`, and the Python directory is described as a version that needs 3.11 or newer with its own readme.
The mismatch is a consequence of the two-implementation design rather than a mistake, but it costs a reader who arrives through metadata. Someone reading the language field expects a Python project, finds a TypeScript build script as the first step in the quick start, and only later learns that `cd python` and `pip install -e .` is the route they wanted.
The page itself is written in Chinese, with an English translation tracked as `README_EN.md`, an `en/` directory beside `docs/`, and an English route on the published site. The release history is one entry, v1.0.0 dated 2026-03-31, and the last push on the default branch is dated 2026-07-09.
Editorial conclusion
Read this project as a tutorial with an unusually complete test setup, not as a drop in replacement for Claude Code, and its own disclaimer says as much: it is built from publicly observable behaviour and makes no claim about matching the real internals, and Claude Code is a trademark of Anthropic. Before you rely on it, check three things. First, decide which chapter count you are working from, since the page gives three. Second, decide whether you want the TypeScript build or the Python port, because the entry points are named differently and the Python side needs 3.11 or newer. Third, pick a permission mode deliberately: `--yolo` executes dangerous commands without asking, `--dont-ask` refuses anything that would need a prompt, and the default mode can ask when an action needs confirmation, subject to its permission rules.
Frequently asked questions
How do I build my own claude-code-from-scratch?
Clone the repository, then run `npm install && npm run build`, which compiles with tsc and is what creates the `mini-claude` binary. Start it with `npm start` for the interactive REPL. The Python route instead needs Python 3.11 or newer, `cd python` and `pip install -e .`.
Do I need an API key to try the claude-code-from-scratch chapters?
No. `node steps/run.mjs --list` enumerates the runnable chapters and `node steps/run.mjs 7` runs one against a local mock model without network access. The `--live` flag is the door to a real model, and `--py` switches a chapter to the Python version.
How many tools does this Claude Code rebuild implement?
Thirteen, described as 6 core plus web_fetch, tool_search, skill, agent and plan mode. The comparison on the page puts Claude Code itself at 66 or more built-in tools, and chapter 2 names 66 tools as the counterpart to this project's tools file.
What permission modes does claude-code-from-scratch offer?
Five. The default asks before acting, `--plan` analyses without modifying, `--accept-edits` approves file edits automatically, `--yolo` skips safety confirmation so dangerous commands run, and `--dont-ask` is the CI mode that refuses anything needing confirmation. The Python port exposes the same five flags on `mini-claude-py`.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/windy3f3f3f3f-claude-code-from-scratch)Star history chart for your README
[](https://hysenlabs.com/projects/windy3f3f3f3f-claude-code-from-scratch)Was this useful?