PI from Scratch
A super-mini pi built in 600 lines of TypeScript that teaches you to write your own coding agent from zero.
Evidence shows an educational coding agent whose built-in tools read/write files and execute commands (the e2e test directly demonstrates file writing). Zero runtime dependencies justifies a full dependency_security score; data flow is relatively transparent thanks to the article-plus-Trace-breakpoint design. Deductions: no user confirmation mechanism for shell execution or file writes, no rollback/undo design, external effects unguarded with no stated boundaries, API key handled only via env vars without leak-prevention notes, and least privilege is not evidenced — tools get arbitrary command execution.
Tests cover the core agent-loop paths (plain text, tool_call execution and result re-injection, unknown-tool error re-injection) and session persistence round-trip, consistent with the architecture README describes; the e2e script fails fast with a clear message when the API key is missing. Deductions: unknown-tool failures are surfaced as strings fed back into the Context rather than clear user-facing errors; the 'GLM-5.2' model name cited in e2e is of doubtful authenticity; no evidence of retry/rate-limit handling.
Audience and scenario are very clear: developers wanting to understand pi's data flow from scratch; the README's tone and structure serve this goal — full marks. Model name and base URL are configurable over an OpenAI-compatible API, so environment fit is adequate. Deductions: trigger precision is inapplicable/unsupported; capability boundaries are only implied by the 'educational' framing, with no explicit statement of production limits; Node 22+ is required with no fallback noted.
Install notes are complete (Node 22+, npm install, env vars, running the local site, e2e usage); a LICENSE file matching the MIT metadata in package. earns a full license score. The information architecture (article + progressively filling editor + Trace) is distinctive. Deductions: no CHANGELOG, no known-limitations section, no contribution/maintenance guidance; publisher identity unverified with no maintenance commitment evidence; only one e2e example and no FAQ; version still at 0.1.0.
Output is a structured event stream (assistant_text/tool_call/tool_result/turn_end) with session persistence, so usability is fair; the marginal value of a 600-line agent loop is educational rather than a production substitute, which the README states honestly. Deductions: as an actual Agent product, output usability is limited (no confirmation, audit, or interrupt/resume); cost-benefit depends on learning intent, with limited general task value; the '600 lines' headline figure cannot be verified from the given files.
Test files correspond to the claimed core paths, and README links to the upstream pi repo and pi-book for traceability. Deductions: claims like '600 lines' and 'all components intuitive' lack in-file support; sponsor endorsements (OpenModel, Cubence) are promotional, with facts and marketing not separated; corroboration beyond upstream links is thin, and this being a static review, no execution-based verification was performed.
- The tools can execute arbitrary shell commands and read/write files with no confirmation or sandbox mechanism observed; run only in an isolated environment and never against untrusted tasks.
- This is an educational project, not a production agent: no rollback, no audit trail, no stated limitations — do not use it to auto-modify real codebases.
- Sponsor endorsements in the README (OpenModel, Cubence) include referral links and codes; treat them as marketing and evaluate independently.
- The API key is passed via environment variables; avoid leaking it in shell history or logs. Note the e2e test writes and deletes files under /tmp.
- The 'GLM-5.2' model name cited in the e2e script is unverified; confirm your actually available model before running.
- Figures such as '600 lines' are author claims that this static review could not verify.
What does this agent do, and when should you use it?
PI from Scratch is an educational project (repository SaladDay/pi-from-scratch) that implements a minimal coding agent called nano-pi in roughly 600 lines of TypeScript. It follows the data flow of the open-source project pi, stripping away engineering details while keeping the core ideas, to explain how an agent loop and tool-calling actually work. The agent can read files, edit code, and execute commands, and at runtime requires an OpenAI-compatible API and a model name. The companion website presents the article and source code side by side: as you read, the editor on the right progressively completes the code, and a Trace feature lets you set breakpoints and step through execution line by line. The online trace is pre-generated static data, so browsing the site triggers no model requests. It is aimed at engineers who want to understand how pi-style coding agents work internally, not at direct production adoption.
nano-pi implements a minimal runnable coding agent loop in TypeScript: it calls a large language model through an OpenAI-compatible endpoint (default https://api.openai.com/v1) and lets the model read files, modify code, and execute commands. After installation it starts with npm run dev, using NANOPI_API_KEY for credentials, with NANOPI_MODEL to set the model and NANOPI_BASE_URL to point at a compatible endpoint. The tutorial site (pi-from-scratch.vercel.app) shows the article and nano-pi source together, with the editor completing the code progressively as you read, plus a Trace breakpoint mode for stepping through execution; traces on the site are pre-generated static data and consume no model calls.
- Engineers who want to understand agent loops and tool-calling by reading a ~600-line minimal pi-style coding agent
- Developers planning to build their own agent on top of pi who want to first grasp its data flow via the stripped-down nano-pi
- Teaching or team-sharing sessions that use Trace breakpoints to walk through agent code execution line by line
- Readers of pi-book who want to hands-on re-implement nano-pi from zero before going deeper into pi
- Self-learners who prefer reading an article while the corresponding code fills in progressively in a side editor
What are this agent's strengths and limitations?
- Tiny footprint: a complete agent loop in roughly 600 lines of TypeScript, with very low reading cost
- Companion site combines article, progressively completed source, and Trace breakpoint tracking to visualize execution flow
- Follows pi's data flow decomposition, keeping core ideas and removing engineering noise for a clear learning path
- NANOPI_BASE_URL makes it compatible with any OpenAI-compatible endpoint, avoiding lock-in to a single model provider
- Positioned as a teaching project, not a production tool — unsuitable as a day-to-day coding agent
- Requires Node.js 22+ and your own OpenAI-compatible API; key management and API costs are on the user
- Defaults to the OpenAI-compatible protocol, so incompatible services need extra adaptation
- No evidence of tests, releases, or other engineering rigor in the repository, making quality and maintenance uncertain
How do you install or deploy this agent?
Requires Node.js 22 or higher and an OpenAI-compatible API key. After cloning the repository:
bash
npm install
export NANOPI_API_KEY=your-api-key
npm run devOptional environment variables: NANOPI_MODEL (model name) and NANOPI_BASE_URL (OpenAI-compatible endpoint, default https://api.openai.com/v1).
To run the tutorial site locally:
bash
cd web
npm install
npm run devHow do you use this agent?
Set NANOPI_API_KEY (plus optional NANOPI_MODEL and NANOPI_BASE_URL) and run npm run dev to start nano-pi, which sends requests to your chosen OpenAI-compatible endpoint. To learn the implementation, read online at pi-from-scratch.vercel.app: the right-hand editor completes the nano-pi code as you progress, and the Trace feature supports breakpoints and line-by-line execution tracking; online traces are static pre-generated data, so browsing triggers no model requests.
How does this agent compare with similar options?
The project is explicitly modeled on the open-source project pi: pi is the full engineering implementation, while this repo strips away pi's engineering details and keeps the core ideas in roughly 600 lines. The README also points to the pi-book as a deeper follow-up reference after finishing nano-pi.