pi-from-scratch : un agent de codage TypeScript en 600 lignes, et le site qui l'explique

Le problème : la boucle d'agent reste une boîte noire

La plupart des coding agents s'utilisent comme des binaires. On leur donne un objectif, ils lisent des fichiers, modifient du code, lancent des commandes, et on ne voit jamais l'ordonnancement interne. pi-from-scratch prend le problème par l'autre bout : il part de pi, un agent existant, et en retire ce que le README appelle les détails d'ingénierie pour ne garder que les idées centrales. Le résultat s'appelle nano-pi, présenté comme environ 600 lignes de TypeScript couvrant la lecture de fichiers, la modification de code et l'exécution de commandes.

Le public visé est précis. Un développeur qui a déjà écrit du TypeScript, qui sait ce qu'est un appel d'outil dans une API de modèle, mais qui n'a jamais assemblé lui-même la boucle qui décide quand lire un fichier, quand appliquer un patch et quand s'arrêter. Pour ce lecteur, le dépôt n'est pas une bibliothèque : c'est un support de lecture, doublé d'un exécutable qu'on peut lancer pour voir le comportement réel. Le README assume ce positionnement avec une phrase directe : ce n'est pas un livre, c'est un article.

nano-pi : un flux linéaire plutôt qu'un framework

Le README décrit la méthode : le projet décompose le flux de données de pi, puis reconstruit chaque composant au moment où il devient nécessaire. Autrement dit, pas d'abstraction posée à l'avance. On ne trouve donc pas de couche de plugins, pas de registre d'outils générique, pas de système d'événements. Ce qui existe, c'est une boucle qui envoie une requête à un modèle compatible OpenAI, reçoit éventuellement une demande d'appel d'outil, exécute cet outil, réinjecte le résultat dans la conversation, et recommence.

Le choix du format d'API est structurant. En se limitant à une interface compatible OpenAI, configurable par URL de base, le projet évite d'implémenter plusieurs protocoles de fournisseurs. La contrepartie est immédiate : tout ce qui n'entre pas dans ce format, comme les blocs de raisonnement ou les appels d'outils propres à d'autres protocoles, n'a pas de chemin évident dans le code. C'est cohérent avec l'objectif pédagogique, mais cela veut dire que nano-pi n'est pas un client multi-fournisseurs, et le README ne prétend pas le contraire.

Le site ajoute une seconde couche au dépôt : un éditeur qui se remplit au fil de la lecture, et un traceur qui permet de poser des points d'arrêt et d'avancer ligne par ligne. C'est probablement la partie la plus utile du projet pour quelqu'un qui bloque sur l'ordre des opérations, parce qu'un agent se comprend mal en lisant du code statique. Le README précise que le traceur en ligne est constitué de données statiques pré-générées : consulter le site ne déclenche aucune requête vers un modèle.

Démarrer nano-pi en trois commandes

Le README donne la séquence complète. Il faut Node.js 22 ou plus récent, et une clé pour une API compatible OpenAI.

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

Trois variables d'environnement sont documentées, dont une seule est obligatoire. NANOPI_API_KEY porte la clé. NANOPI_MODEL permet de choisir le nom du modèle. NANOPI_BASE_URL pointe vers l'endpoint compatible OpenAI et vaut https://api.openai.com/v1 par défaut. Cette dernière est celle qui compte si vous passez par un relais ou un fournisseur tiers : c'est le seul levier de configuration réseau exposé.

Le site de cours se lance séparément, depuis le sous-répertoire web, avec cd web puis npm install et npm run dev. Les deux parties du dépôt ont donc leur propre installation, et l'installation de la racine ne suffit pas à faire tourner le site. Aucun fichier de configuration n'est mentionné dans le README : toute la configuration passe par l'environnement, ce qui simplifie le démarrage mais rend la reproductibilité d'une session dépendante de votre shell.

Ce que le dépôt ne couvre pas

Le README ne mentionne ni gestion des permissions, ni liste blanche de commandes, ni sandbox d'exécution. Pour un projet dont l'intérêt est justement d'exécuter des commandes, c'est la limite la plus sérieuse. Un agent qui exécute ce que le modèle décide, sans garde-fou documenté, n'a pas sa place dans un environnement où il peut toucher à des secrets ou à un dépôt partagé. Ce n'est pas un défaut de conception dans un contexte pédagogique, mais c'est un point à vérifier dans le code avant toute autre utilisation.

Deuxième angle mort : la persistance. Rien dans le matériel fourni n'indique comment une session est sauvegardée, reprise après une erreur, ou limitée en nombre de tours. La fenêtre de contexte et son élagage ne sont pas décrits non plus. Sur un agent de codage, ce sont précisément les sujets qui font la différence entre une démonstration et un outil utilisable au quotidien.

Troisième point, plus prosaïque : le README ne publie pas d'arborescence ni de liste de fichiers. Le chiffre de 600 lignes est une annonce, pas un inventaire vérifiable depuis ce document. Il faut ouvrir le dépôt pour savoir comment le code est découpé, et si ce découpage correspond à la progression du site. Enfin, le README ne renvoie à aucune release : la distribution se fait par le dépôt lui-même.

Face à quoi le comparer

L'alternative naturelle n'est pas un autre agent de codage, c'est un framework d'orchestration comme LangChain ou LangGraph. La différence d'approche est nette. Ces bibliothèques fournissent des abstractions réutilisables : graphes d'états, gestion de mémoire, intégrations de fournisseurs, outils de traçage. Vous écrivez votre agent en assemblant ces briques, et vous héritez de leur surface d'API et de leur rythme de version.

pi-from-scratch fait l'inverse. Il n'y a pas de brique à assembler : le flux est écrit à la main, dans l'ordre où il s'exécute. Vous obtenez une compréhension directe de chaque étape, et un code que vous pouvez modifier ligne par ligne sans lire de documentation externe. Vous perdez tout ce que les frameworks apportent par ailleurs : support multi-fournisseurs, mémoire, reprise, observabilité.

Le choix dépend donc de ce que vous cherchez. Pour apprendre, le code linéaire est plus efficace qu'un graphe d'états, parce qu'il n'y a rien à démêler avant de comprendre. Pour livrer, l'inverse est vrai : réécrire à la main ce qu'un framework fournit déjà revient à payer en maintenance ce que vous avez économisé en compréhension. Le README cite par ailleurs pi-book comme source d'inspiration et comme suite logique pour approfondir pi lui-même, ce qui situe le projet dans une progression plutôt que comme un point d'arrivée.

Coût de suivi et licence

Le dépôt est sous licence MIT, ce qui autorise la réutilisation, la modification et la redistribution, y compris dans un contexte commercial, à condition de conserver l'avis de licence. Ce n'est pas un avis juridique : lisez le fichier LICENSE du dépôt si la question est structurante pour vous.

Sur le suivi, le matériel fourni donne peu d'éléments. Aucune release n'a été récupérée, et le README ne décrit pas de politique de version. Le dernier push enregistré date du 18 août 2026. Un projet de ce type a une maintenance de nature différente d'une bibliothèque : le code est un support de cours, donc il évolue quand l'explication change, pas quand une dépendance casse. Concrètement, la dépendance à surveiller est Node.js, puisque le README fixe un plancher à la version 22, et l'API du fournisseur compatible OpenAI que vous branchez derrière NANOPI_BASE_URL. Si vous forkez nano-pi pour en faire un outil interne, la maintenance de la boucle d'appels d'outils vous revient entièrement, et le dépôt d'origine ne fournira probablement pas de correctifs pour ce cas d'usage.

Conclusion éditoriale

pi-from-scratch s'adresse à un développeur TypeScript qui veut lire, exécuter et modifier une boucle d'agent de bout en bout, pas à une équipe qui cherche un outil à déployer. Si votre besoin est un agent qui tourne en CI, le projet n'a ni gestion de permissions, ni persistance de session, ni mécanisme de reprise documentés, et rien dans le README ne suggère qu'ils existent. Avant d'investir du temps, vérifiez deux points dans le dépôt : le contenu réel de src/ (600 lignes annoncées, mais aucune arborescence n'est publiée dans le README) et la version de Node.js exigée, 22 ou plus, qui est un plancher plus élevé que celui de beaucoup de projets TypeScript.

Sources officielles

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