pi-from-scratch: a 600-line TypeScript agent you read instead of install
600 行 TypeScript 写成的超级迷你版 pi，让你轻松从 0 写出属于你的 pi-agent
At a glance
- What is it?
- SaladDay's nano-pi is a teaching implementation of a coding agent, shipped as a scrolling article with a live editor and a steppable trace. It is worth your evening if you want to understand the agent loop; it is not a tool you adopt.
- Who is it for?
- Read it if you have written tool-calling code before and want to see the whole loop in one sitting, or if you are evaluating pi and want its data flow stripped of engineering detail. Skip it if you need a coding agent for daily work: nano-pi is a teaching artifact with no test suite, no sandboxing story and no release history in the material provided.
- 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 29 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What nano-pi actually is, and who the article is written for
The README opens with a plain claim: this is a TypeScript coding agent that reads files, edits code and runs commands, written from zero in roughly 600 lines. The framing sentence is that the project follows pi's data flow and rebuilds only what is needed, so that every component is intuitive. The stated goal is to delete pi's engineering detail and keep its core idea.
That makes the audience narrow and specific. It is for a developer who already knows what tool calling is and wants to see the whole turn structure laid out in one readable file set. The author says so directly: relax, this is an article, not a book. The website puts the prose and the source side by side, and as you scroll the editor on the right fills in the code, so by the end the full nano-pi source is on screen. There is also a Trace view where you can set breakpoints and step through execution line by line.
The problem it solves is not "I need an agent". It is "I have used agents and I still cannot picture the loop". Most production agents hide the interesting part behind abstractions for retries, streaming, permissions and provider quirks. nano-pi inverts that trade: it keeps the loop visible and drops the rest.
The loop the article walks through: model output in, tool result back
The material does not publish the source inline, so the mechanism has to be described at the level the README supports. What is confirmed is the shape: a TypeScript agent that reads files, modifies code and executes commands, following pi's data flow, with tool calling as a topic tag on the repository. The Trace feature exists precisely because the execution order is the thing being taught, which tells you the project expects the flow to be non-obvious enough to deserve breakpoints.
So the architecture to expect is a single loop: send the conversation plus tool definitions to an OpenAI-compatible endpoint, receive either text or a tool call, dispatch the tool locally (read a file, write a file, run a shell command), append the result as a new message, and send the whole thing back. The interesting decisions in such a loop are all about termination and state. When does the agent stop? What happens when the model calls a tool that does not exist? How is the conversation trimmed when it grows past the context window? The article's value is that it forces those questions into the open, because at 600 lines there is nowhere to hide them.
One thing the README does state about the site: the online trace is pre-generated static data, so browsing the website does not issue model requests. That is a deliberate design choice and a good one. The teaching artifact is deterministic and free to explore, independent of whether you have an API key.
Running nano-pi: three commands and three environment variables
The README gives the setup without ceremony. You need Node.js 22 or higher, plus an OpenAI-compatible API. Then:
npm install export NANOPI_API_KEY=your-api-key npm run dev
There are three optional environment variables. NANOPI_MODEL sets the model name. NANOPI_BASE_URL points at an OpenAI-compatible endpoint and defaults to https://api.openai.com/v1. NANOPI_API_KEY is the only required one.
The teaching website is a separate install. From the repository root you cd into web, run npm install, then npm run dev. Two package installs, two dev servers, one repository.
That is the whole documented surface. There is no config file, no CLI flag list, no plugin directory. For a tutorial that is correct: every knob you add is a knob the reader has to skip past. But it also means the only way to change behaviour beyond model and endpoint is to edit the TypeScript. If you were hoping to point nano-pi at a local model server, NANOPI_BASE_URL is the lever, and nothing in the README says which non-OpenAI-compatible shapes will or will not work.
The limits you should assume before you start
The README never claims nano-pi is safe or complete, and the omissions are consistent with a teaching project rather than an oversight. There is no mention of a sandbox, a permission prompt, a command allowlist or a diff review step before a write lands. An agent that executes commands and edits files without those guards is fine when you are reading its source on your own machine and pointed at a throwaway directory. It is the wrong tool the moment you point it at a repository you care about, or at a model you do not control.
There is also no release history in the material provided, no test suite mentioned, and no statement about how the loop handles a malformed tool call or an API error mid-turn. Those are exactly the paths a production agent spends most of its code on, and they are the paths a 600-line teaching implementation is most likely to elide. Treat any claim about nano-pi's resilience as unverified until you read the source.
Finally, the scope is one loop. There is no mention of subagents, MCP servers, context compaction, session persistence or multi-file planning. If your question is "how do I structure a large agent", this article answers a different question.
pi versus nano-pi: the same idea with and without the engineering
The natural comparison is the project nano-pi is derived from. pi is the real coding agent; nano-pi is the same data flow with the engineering detail removed, by the author's own description. That is the entire difference in approach, and it is a useful one to name precisely.
In pi, the parts you would delete are the parts that make it survive contact with real work: provider differences, retry and error handling, streaming, permission and sandbox policy, session state, and whatever tooling surrounds the loop. In nano-pi those are gone, which is why you can hold the whole thing in your head. The cost is symmetrical. You cannot swap nano-pi in for pi and expect the same behaviour, because the behaviour you would be relying on is the part that was cut.
A second reference point appears in the README's thanks section: pi-book, cited as an influence and recommended for readers who want to go deeper into pi after finishing nano-pi. That is a reasonable ordering. nano-pi gives you the loop; pi-book is where you go when the loop is no longer the confusing part.
Maintenance cost, licence and the sponsorship footnote
Maintenance is close to zero by construction. The repository is not archived, the last push is dated 2026-08-18, and there are no releases retrieved. A tutorial whose source is frozen into a scrolling article does not need a release cadence; it needs to stay correct. The risk is the opposite of abandonment: if the OpenAI-compatible API surface it targets shifts, or if pi's data flow changes, the article's accuracy drifts and there is no test suite named in the README to catch it.
The licence is MIT, which permits reuse and modification with the usual attribution and warranty disclaimer. That makes the code a legitimate starting point to copy from. It says nothing about the API keys you feed it, and nothing about the third-party services mentioned in the README.
Those services are worth reading carefully. The thanks section credits OpenModel for API testing support and Cubence as a sponsor, both with referral links, and both described as API relay or gateway providers. This is a sponsored tutorial, and the sponsorship sits next to the instructions for pointing nano-pi at an endpoint. That does not make the article wrong, but it does mean the recommended path through the material runs past commercial links, and you should decide on your own provider before you set NANOPI_BASE_URL.
How to decide in ten minutes
Open the site and scroll to the point where the editor has filled in the tool dispatch code. If that section reads as obvious to you, close the tab; you already have the mental model and the remaining 500 lines will not change it. If it reads as a relief, because you had been guessing at this part, finish the article and then step through the Trace with the breakpoints on.
If you are choosing between this and dropping a production agent into a repository, the decision is not close. nano-pi has no documented sandbox, no permission gate and no error-handling story, and the README does not pretend otherwise. Use it to learn the shape of the loop, then read pi or pi-book for the parts that were deliberately removed. The one thing to verify before running anything is what your NANOPI_BASE_URL and NANOPI_API_KEY actually point at, since that is the only configuration the project exposes.
Editorial conclusion
Read it if you have written tool-calling code before and want to see the whole loop in one sitting, or if you are evaluating pi and want its data flow stripped of engineering detail. Skip it if you need a coding agent for daily work: nano-pi is a teaching artifact with no test suite, no sandboxing story and no release history in the material provided. Before you run it, check the Node version requirement of 22 or higher and confirm what NANOPI_API_KEY is being sent to, because the README's only stated default endpoint is https://api.openai.com/v1.
Community notes