# pi-from-scratch: a 600-line TypeScript guide to building a pi-style coding agent

> SaladDay/pi-from-scratch is a teaching repository and companion site that walks through a minimal TypeScript coding agent called nano-pi, following the data flow of pi. It is for engineers who want to read an agent loop end to end rather than install a framework.

**SaladDay/pi-from-scratch** — 600 行 TypeScript 写成的超级迷你版 pi，让你轻松从 0 写出属于你的 pi-agent

- Repository: https://github.com/SaladDay/pi-from-scratch
- Website: https://pi-from-scratch.vercel.app
- Stars: 1,260 · Forks: 101
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/saladday-pi-from-scratch

## What pi-from-scratch is for, and who should read it

Most agent repositories hand you a working binary and a configuration file. You learn the surface: which flags exist, which tools are enabled, where the transcript is written. pi-from-scratch takes the opposite route. It is a 600-line TypeScript project that reimplements the core of pi, a coding agent, so that every component is something you could have written yourself. The README states the intent plainly: strip pi's engineering detail, keep pi's core ideas. The repository name in package.json describes it the same way, as a guide to building your own pi-agent from scratch.

The audience is narrow and worth stating. If you have used a coding agent and want to know what happens between the user message and the file edit, this is the material. If you are teaching an agent loop to a class or a study group, the site format, an article with the source assembling beside it, is unusual and useful. If you want a tool to run against a production repository tomorrow, keep looking. The README frames the project as an article, not a book, and the runnable piece is a byproduct of the explanation rather than the product.

## The mechanism: an agent loop, tool calls, and a trace you can step through

The project follows pi's data flow and rebuilds each stage. The topics list in package.json names the pieces: agent-loop, tool-calling, llm, llm-agent. So the shape is the familiar one for this class of tool. A loop sends the conversation to a model, the model returns a tool call, the tool runs, the result goes back into the conversation, and the loop repeats until the model stops asking for tools. The README describes nano-pi as able to read files, modify code, and execute commands, which is the minimum tool set for a coding agent.

What distinguishes the repository is the delivery. The website puts the article and the source side by side: as you read, the editor on the right fills in code progressively, and by the end the whole of nano-pi is visible. There is also a Trace view that lets you set breakpoints and step through execution line by line. That is the part worth copying for other teaching projects, because an agent loop is hard to follow in prose. Control passes between your code and a remote model, and the interesting state is the message list, which is invisible unless someone shows it to you.

One detail from the README matters for anyone evaluating the trace: the online trace is pre-generated static data, and browsing the site does not make model requests. That keeps the hosted demo free to run and reproducible, but it also means the trace shows recorded behaviour, not live behaviour. If you want to see how nano-pi handles a model that responds differently than expected, you have to run it locally.

## Running nano-pi locally

The README gives the install steps directly. Node.js 22 or higher is required, along with an OpenAI-compatible API. From the repository root, install dependencies, export an API key, and start the CLI through the dev script.

```bash
npm install
export NANOPI_API_KEY=your-api-key
npm run dev
```

The dev script maps to tsx src/cli.ts, so you are running TypeScript directly without a build step. The build script runs tsc and emits dist/cli.js, which package.json exposes as the pi-from-scratch binary, so a compiled entry point exists if you prefer that route.

Two optional environment variables control where requests go. NANOPI_MODEL sets the model name, and NANOPI_BASE_URL sets the OpenAI-compatible endpoint, defaulting to https://api.openai.com/v1. If you point NANOPI_BASE_URL at a proxy or a self-hosted gateway, the rest of the loop should not need to change, because the interface is the OpenAI chat completions shape. The README does not document which models have been exercised, so treat model choice as your own experiment.

To read the article with its live code panel, the web directory is a separate install. Change into it, install, and start its dev server.

```bash
cd web
npm install
npm run dev
```

That second application is the teaching site, not the agent. Running it locally does not require an API key, since the hosted trace is static data.

## Where pi-from-scratch stops being the right tool

The 600-line budget is the whole point and also the main limitation. Anything that makes an agent pleasant to use over months does not fit: no session persistence across restarts, no permission prompts before a command runs, no sandboxing of executed commands, no context compaction when the conversation outgrows the window. The README does not claim otherwise, and none of these appear in the listed topics. If you need them, you are no longer reading a teaching project, you are building a product, and the article will have served its purpose by then.

There is a second, quieter limitation. The README notes that online traces are pre-generated, so the hosted experience is a recording. A reader who only uses the website will see the loop succeed on curated inputs. Real models return malformed tool arguments, refuse, or call a tool that does not exist. How nano-pi handles those cases is exactly what you would want to see, and it is what the static trace is least likely to show you.

Finally, the dependency list in package.json is empty at runtime. Everything the agent needs is either in Node.js 22 or written in the repository. That is a deliberate choice for readability, and it means there is no third-party HTTP client or schema validator to fall back on. You are reading, and maintaining, all of it.

## How it compares with pi and with pi-book

The README is explicit that pi-from-scratch is derived from pi, at github.com/earendil-works/pi, and that the project's approach is to remove pi's engineering detail while keeping its core ideas. That is the real difference between the two: pi is the agent, pi-from-scratch is the explanation of the agent's data flow, with the production concerns taken out. If you want a coding agent to use, pi is the upstream project. If you want to understand one, the smaller repository is the faster read, and you can always go back to pi afterwards to see what the extra code buys.

The README also credits pi-book, at books.antinomie.org/pi/, as an inspiration and recommends it for readers who want to go deeper after finishing nano-pi. The two differ in medium rather than in subject. pi-book is a book about pi; pi-from-scratch is a single article-length walkthrough with the source assembling beside the prose and a step-through trace attached. The README's own framing, that this is an article and not a book, is the honest way to choose between them: pick the article if you want one sitting, pick the book if you want a reference you return to.

## Licence, maintenance, and what upgrading costs

The repository is MIT licensed, and package.json carries the same identifier. That is permissive: you can copy the agent loop into your own project, modify it, and ship it, provided you keep the copyright notice and the licence text. This is a description of the licence terms, not legal advice; if the code ends up inside something commercial, have someone qualified read the LICENSE file.

The last push to the default branch was on 2026-08-18, so the repository is not archived and has been touched within the last two months. There are no retrieved releases, and package.json still says version 0.1.0, so there is no tagged version to pin against. Upgrading means tracking main.

Upgrade cost is low in one sense and non-trivial in another. There are no runtime dependencies, so nothing in the agent can break because a transitive package published a bad minor. The devDependencies are TypeScript 5.6, vitest 2.1, tsx 4.19, and @types/node 22, all caret ranges, so a fresh npm install can pull newer minor versions than the author last ran. The test script is vitest run, and the repository has a test directory, so running the suite after any pull is the cheap way to check that a dependency bump did not disturb the loop.

## Conclusion

Adopt pi-from-scratch if you want to read an agent loop in full, or if you are teaching one, because the site pairs the article with a trace you can step through line by line. Skip it if you need a supported CLI for daily work, since the README describes an article first and a runnable nano-pi second, and the package has no runtime dependencies to lean on. Before relying on it, check the Node.js 22 requirement against your machine, confirm which OpenAI-compatible endpoint and model you will point NANOPI_BASE_URL and NANOPI_MODEL at, and read src/ to see what the 600 lines actually cover.

## FAQ

### What is pi-from-scratch?

It is a repository and companion website that walks through building a minimal TypeScript coding agent called nano-pi, following the data flow of pi. The README describes it as stripping pi's engineering detail while keeping pi's core ideas, and the whole agent is about 600 lines.

### What do I need to run nano-pi from pi-from-scratch?

The README requires Node.js 22 or higher and an OpenAI-compatible API. You install dependencies, export NANOPI_API_KEY, and run npm run dev, with NANOPI_MODEL and NANOPI_BASE_URL available as optional environment variables.

### Does the pi-from-scratch website make model requests while I read it?

No. The README states that the online trace is pre-generated static data and that browsing the website does not initiate model requests. To see live behaviour you have to run nano-pi locally with your own API key.

### Can pi-from-scratch read files and run commands like a real coding agent?

The README says nano-pi can read files, modify code, and execute commands, which is the tool set a coding agent needs. It does not document sandboxing or permission prompts around command execution, so treat that as outside the scope of the 600 lines.

### Is pi-from-scratch the same thing as pi?

No. The README credits pi at github.com/earendil-works/pi as the upstream project whose data flow this repository decomposes. pi-from-scratch is the explanation and the smaller reimplementation, not the production agent.

## Sources

- [Issues](https://github.com/SaladDay/pi-from-scratch/issues)
- [License: MIT](https://github.com/SaladDay/pi-from-scratch/blob/main/LICENSE)
- [Project website](https://pi-from-scratch.vercel.app)
- [README](https://github.com/SaladDay/pi-from-scratch/blob/main/README.md)
- [SaladDay/pi-from-scratch on GitHub](https://github.com/SaladDay/pi-from-scratch)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/saladday-pi-from-scratch