pi-from-scratch: ein Coding-Agent in 600 Zeilen TypeScript, erklärt am Datenfluss von pi

Ein Agent, der Dateien liest, Code ändert und Befehle ausführt

Der Beschreibungstext nennt das Ziel direkt: ein Coding-Agent in rund 600 Zeilen TypeScript, der Dateien lesen, Code verändern und Kommandos ausführen kann. Adressiert sind damit Leser, die bereits wissen, was ein Agent ist, aber noch nicht wissen, welche Schritte zwischen einer Nutzereingabe und einer ausgeführten Dateioperation liegen. Die README formuliert den Anspruch so, dass pi auf seinen Datenfluss heruntergebrochen wird und nur die Kernidee übrig bleibt, während die Projektinfrastruktur von pi entfällt. Das ist eine bewusste Reduktion: Was in einem produktiven Agenten an Konfiguration, Fehlerbehandlung und Werkzeugverwaltung existiert, wird hier weggelassen, damit die Schleife sichtbar bleibt. Der Nutzen liegt also nicht in der Funktionalität, sondern darin, dass jede Zeile einen Zweck hat und beim Lesen nachvollziehbar bleibt. Wer schon einmal versucht hat, einen Agenten aus einer großen Codebasis heraus zu verstehen, kennt das Problem: Die eigentliche Logik verschwindet zwischen Abstraktionen. Hier ist es umgekehrt.

Der Datenfluss als Gliederung, nicht die Ordnerstruktur

Die README beschreibt den Aufbau als Zerlegung entlang des Datenflusses von pi mit der Regel, dass nur gebaut wird, was gerade gebraucht wird. Das ist eine didaktische Entscheidung mit Konsequenz: Die Reihenfolge der Komponenten folgt dem Weg einer Anfrage, nicht einer Schichtenarchitektur. Die Website setzt das um, indem der Editor rechts neben dem Text die Datei nano-pi schrittweise vervollständigt. Wer die Seite bis zum Ende liest, hat den vollständigen Code im Editor gesehen. Zusätzlich gibt es eine Trace-Ansicht, die laut README Haltepunkte erlaubt, um den Code Zeile für Zeile zu durchlaufen. Das ist der eigentliche Mechanismus des Projekts: Der Code und seine Erklärung liegen im selben Medium, und der Fortschritt beim Lesen entspricht dem Fortschritt beim Schreiben der Datei. Wer nur das Repository klont, bekommt diesen Teil nicht mit, weil er an die Website gebunden ist. Der Code allein bleibt lesbar, die Erklärstrecke fehlt dann.

Start mit npm install, NANOPI_API_KEY und Node.js 22

Die README gibt für nano-pi drei Schritte vor. Zuerst npm install, dann das Setzen von NANOPI_API_KEY, dann npm run dev. Zusätzlich existieren zwei optionale Variablen: NANOPI_MODEL für den Modellnamen und NANOPI_BASE_URL für die Adresse eines OpenAI-kompatiblen Endpunkts, wobei der Standardwert https://api.openai.com/v1 ist. Als Laufzeitumgebung wird Node.js 22 oder höher verlangt. Wer die Lehrwebsite lokal betreiben will, wechselt in das Verzeichnis web, führt dort erneut npm install aus und startet mit npm run dev. Wichtig für alle, die den Trace ausprobieren wollen: Die README stellt klar, dass die online gezeigte Trace vorab erzeugte statische Daten sind und beim Besuch der Website keine Modellanfragen ausgelöst werden. Der Trace ist also eine Aufzeichnung, keine Live-Ausführung. Für das lokale nano-pi gilt das nicht, dort läuft der Agent gegen den konfigurierten Endpunkt.

Was das Format nicht leistet

Ein Agent, der Dateien schreiben und Kommandos ausführen darf, braucht Grenzen. Die README nennt keine. Es gibt keinen Hinweis auf eine Sandbox, auf Bestätigungsschritte vor Schreibzugriffen, auf Pfadbeschränkungen oder auf eine Protokollierung der ausgeführten Befehle. Das ist bei einem Lehrbeispiel konsequent, denn jede dieser Schichten würde Zeilen kosten, die vom Datenfluss ablenken. Es ist aber auch die klarste Grenze des Projekts: Wer nano-pi auf ein Arbeitsverzeichnis mit echten Daten richtet, hat keine im Repository dokumentierte Absicherung. Ein zweiter Punkt betrifft die Zielumgebung. Das Projekt hängt an einem OpenAI-kompatiblen Endpunkt und an einem einzelnen Modellnamen aus NANOPI_MODEL. Es gibt in der README keinen Hinweis auf eine Konfiguration mehrerer Modelle, auf Werkzeugfreigaben pro Modell oder auf ein Kontextmanagement über die reine Schleife hinaus. Für einen Produktiveinsatz fehlen außerdem Releases: Die Metadaten führen keine Veröffentlichungen auf, es gibt also keine versionierten Artefakte, an denen man sich orientieren könnte.

Der Unterschied zu einem ausgereiften Agent-Werkzeug

Die naheliegende Alternative ist pi selbst, auf das die README mehrfach verweist und dessen Datenfluss die Gliederung vorgibt. Der Unterschied liegt nicht im Konzept, sondern im Umfang. pi enthält nach der Formulierung der README die Projektinfrastruktur, die hier bewusst entfernt wurde. Wer pi einsetzt, bekommt diese Schichten mit; wer pi-from-scratch liest, bekommt sie nicht und muss sie gedanklich ergänzen. Ein zweiter Referenzpunkt aus der README ist das Buch pi-book, das als weiterführende Lektüre genannt wird, falls man nach nano-pi tiefer in pi einsteigen will. Das ist eine ehrliche Arbeitsteilung: Das Repository ist der Einstieg, das Buch die Vertiefung. Wer stattdessen einen fertigen Agenten für die Arbeit an einem Repository sucht, wird hier nicht fündig, weil nano-pi genau die Teile nicht hat, die den Unterschied zwischen einer Demonstration und einem Werkzeug ausmachen.

Pflege, Lizenz und die Frage der Aktualität

Das Repository steht unter MIT, was die Verwendung des Codes in eigenen Projekten erlaubt, solange der Lizenztext beibehalten wird. Das ist für Lehrmaterial die passende Wahl, weil Leser Abschnitte übernehmen und anpassen können. Zur Pflege lässt sich aus dem Material wenig ableiten: Der letzte Push liegt laut Metadaten auf dem 18. August 2026, Releases sind nicht aufgeführt. Ob die Anbindung an OpenAI-kompatible Endpunkte gepflegt wird, wenn sich Schnittstellen ändern, ist daraus nicht ableitbar. Wer den Code als Grundlage für ein eigenes Projekt nimmt, übernimmt damit auch die Verantwortung für die Anpassung an künftige API-Änderungen. Für ein Projekt dieser Größe ist der Aufwand überschaubar, aber er ist vorhanden und wird vom Repository nicht abgenommen. Die README nennt zwei Sponsoren, die API-Zugang bereitstellen, und weist darauf hin, dass der Autor selbst keine API-Kosten trägt. Das ist eine Offenlegung, keine technische Aussage.

Einordnung: Lehrmaterial mit klarer Zielgruppe

Der Untertitel der README sagt, es sei ein Artikel und kein Buch, und genau so sollte man das Projekt behandeln. Der Wert liegt in der Verbindung von Text, schrittweise wachsendem Editor und Trace-Ansicht. Wer einen Agenten von Grund auf verstehen will, kann hier den Datenfluss nachvollziehen, ohne sich durch eine große Codebasis zu arbeiten. Wer dagegen einen Agenten sucht, der in einer echten Umgebung mit Schreibrechten arbeitet, braucht die Teile, die hier fehlen: Sandbox, Bestätigungsschritte, Kontextverwaltung, versionierte Releases. Die Entscheidung hängt damit nicht an der Qualität des Codes, sondern am Zweck. Zum Lernen ist die Reduktion ein Vorteil, im Betrieb ist sie ein Mangel.

Redaktionelles Fazit

Wer verstehen will, wie ein Coding-Agent intern Daten weiterreicht, findet hier ein kleines, lesbares Beispiel mit Trace-Ansicht; wer einen Agenten für den täglichen Einsatz in einem echten Repository braucht, sollte zu einem ausgereiften Werkzeug greifen. Vor dem Start ist zu prüfen, ob Node.js 22 oder höher installiert ist, ob ein OpenAI-kompatibler Endpunkt samt Schlüssel bereitsteht und ob das Verhalten des Agenten bei Schreib- und Kommandooperationen den eigenen Anforderungen genügt. Das Repository liefert dafür keine Sicherheitsmechanismen, sondern ausschließlich den Kern der Schleife.

Offizielle Quellen

1. Issues
2. License: MIT
3. Project website
4. README
5. SaladDay/pi-from-scratch on GitHub