Dans pi, l'outil à 92 000 étoiles pour créer votre agent IA

Claude Code, Codex et Gemini CLI sont des harnais d'agent conçus par quelqu'un d'autre — et si tu passes ta journée de travail dans l'un d'eux, tu vis avec ce choix de conception. Tu veux changer un comportement, ajouter un outil, resserrer une règle de permission ? Tu attends que l'éditeur le fasse. Tu ne connais pas le contenu du system prompt, tu ne vois pas la boucle qui exécute les outils, et tu ne peux rien changer, alors même que ces outils sont devenus le poste de travail principal de milliers de développeurs.

Un projet open source prend le contre-pied total : pi, un toolkit qui livre les pièces détachées pour assembler ton propre agent, du connecteur au modèle jusqu'à l'interface. Il a récolté 92 000 étoiles GitHub en un an et livre une release à peu près chaque semaine. Cet article couvre ce que pi met vraiment dans la boîte, comment construire son propre agent avec son SDK, et un verdict honnête face aux harnais tout faits.

Un harnais, c'est toute la mécanique autour d'un modèle de langage qui en fait un agent fonctionnel. Un modèle seul ne fait qu'une chose : lire du texte et produire du texte. Il ne lit pas tes fichiers, il n'exécute aucune commande, et il ne se souvient de rien d'une session à l'autre. Tout le reste, c'est le harnais — le system prompt qui cadre le modèle, les outils qu'on lui expose, la boucle qui exécute les appels d'outils et renvoie les résultats, et l'interface dans ton terminal.

Le harnais décide aussi des détails qui comptent au quotidien : comment l'historique se compacte quand le contexte déborde, comment une erreur d'outil remonte au modèle, ce qui est loggé ou non. Claude Code est un harnais. Codex aussi. Quand un agent t'impressionne, une bonne part du mérite revient à cette mécanique plutôt qu'au modèle — branche le même modèle sur deux harnais différents et tu obtiens deux agents qui n'ont pas le même niveau.

pi, construit par Earendil Works, découpe cette mécanique en briques réutilisables. Tu peux utiliser son agent de code tel quel, ou prendre les briques une par une pour bâtir le tien. La seconde option est celle qui nous intéresse.

pi est un monorepo — un seul dépôt hébergeant cinq paquets publiés séparément — et chaque paquet couvre un étage du harnais :

Paquet	Ce qu'il fait
pi-ai	API unifiée vers OpenAI, Anthropic, Google et le reste : streaming des réponses, blocs de raisonnement avec leurs niveaux, découverte dynamique des modèles de chaque fournisseur. Change de labo en changeant un argument.
pi-agent-core	La boucle d'agent elle-même : état de la conversation, plus le cycle qui envoie le message, lit les appels d'outils, les exécute et renvoie les résultats jusqu'à la fin de la tâche. Les cas tordus — un outil qui échoue, une réponse coupée, des appels parallèles — sont déjà gérés.
pi-tui	Bibliothèque de rendu terminal en rendu différentiel : elle ne redessine que ce qui change à l'écran.
pi-coding-agent	L'agent de code complet assemblé à partir des briques ci-dessus — la preuve que le toolkit suffit à bâtir un produit fini.
pi-telemetry	Branche tes propres métriques d'usage sans dépendre d'un fournisseur.

La boucle d'agent est exactement le morceau que tu réécrirais mal de zéro ; l'écrire proprement représente des semaines de travail que tu récupères en un import. L'équipe applique la même recette ailleurs : un dépôt à part, pi-chat, réutilise les mêmes briques pour l'automatisation de conversations.

Les chiffres montrent que la formule marche :

Métrique	Valeur
Étoiles GitHub	92 123
Forks	11 400
Commits	5 700+
Licence	MIT
Releases sur les deux premières semaines d'août 2026	3 (v0.84.2 livrée le 14 août)

La licence MIT signifie que tu peux utiliser, modifier et redistribuer pi sans restriction, y compris dans un produit commercial. pi n'est pas un framework de plus : c'est un harnais complet livré en pièces détachées, maintenu à un rythme soutenu.

Le CLI pi est l'agent de code assemblé que tu obtiens avant de toucher au moindre code, et c'est là que tu vas commencer. L'installation tient en une ligne, et son flag --ignore-scripts n'est pas un détail : il empêche tes dépendances d'exécuter leurs scripts d'installation, l'une des failles les plus exploitées sur npm. Lance pi, connecte ton fournisseur avec la commande de login, et tu as un agent de code dans ton terminal. La barre d'état affiche le dossier courant, la session, les tokens consommés et le coût en temps réel — tu vois chaque requête chiffrée au moment où elle part, au lieu de découvrir la facture en fin de mois.

Les commandes slash couvrent le quotidien : model pour changer de modèle en cours de route, compact pour résumer l'historique quand le contexte déborde, export pour extraire la conversation, settings pour le reste. Un fichier markdown déposé dans le dossier des prompts devient une commande qu'on déclenche en tapant son nom.

La vraie signature de pi, c'est la gestion des sessions. Chaque conversation est sauvée en JSONL dans ton dossier personnel, triée par projet — et l'historique est un arbre, pas une ligne. Tu peux revenir à n'importe quel point d'une conversation et repartir dans une autre direction avec fork, puis naviguer entre les branches avec tree. Un prompt raté ne coûte plus rien : reviens au nœud précédent et réessaie sans perdre la branche d'avant. Comme tout est stocké en local, resume te ramène dans n'importe quelle session passée, même des semaines plus tard. Ni Claude Code ni Codex n'offrent une navigation d'historique sous cette forme.

Par défaut, le modèle ne dispose que de quatre outils : read, write, edit et bash. C'est très peu face aux agents du marché, et c'est délibéré (on y revient plus bas). La configuration suit la même logique : un fichier de réglages global dans le dossier personnel, un fichier par projet qui le surcharge, et un système de confiance qui demande confirmation avant d'appliquer les réglages locaux d'un dossier ouvert pour la première fois. Si tu migres, pi charge automatiquement tes fichiers AGENTS.md ou CLAUDE.md existants comme contexte, donc tes instructions marchent sans réécriture.

Construire un agent avec le SDK de pi commence par un seul import : createAgentSession, à qui l'on passe un runtime de modèle et un gestionnaire de session, renvoie un agent fonctionnel. Le gestionnaire de session, c'est le choix de persistance — en mémoire pour un script jetable, ou sur disque pour retrouver les conversations d'un run à l'autre.

On l'a testé sur un projet local. Notre script demande ce qu'il y a dans le dossier courant ; l'agent appelle son outil read, lit le dossier et répond. C'est la boucle complète, écrite par nous, en une dizaine de lignes de TypeScript. Les sessions créées par le SDK ont la même structure en arbre que celles du CLI — chaque message est lié à son parent — donc le branchement d'historique fonctionne aussi dans ton propre code.

Les outils custom, c'est là que ça devient intéressant. defineTool prend un nom, une description, un schéma de paramètres typé et une fonction d'exécution, et ton outil apparaît au modèle exactement comme read ou bash. On en a écrit un qui interroge la liste des vidéos de la chaîne, passé dans customTools, et l'agent l'a appelé tout seul dès la première question pertinente. C'est essentiellement le même mécanisme qu'un serveur MCP, sauf que tout vit dans ton fichier — pas de processus séparé, pas de protocole entre les deux. Comme le schéma de paramètres est typé, ton éditeur autocomplète les arguments et l'agent reçoit des entrées déjà validées.

Tu contrôles aussi le modèle, le niveau de réflexion (de complètement désactivé jusqu'à max), la liste exacte des outils que voit le modèle, et même tout le system prompt via un chargeur de ressources si tu veux repartir d'une page blanche. Côté affichage, session.subscribe te donne chaque événement — texte en streaming, appels d'outils, erreurs — à rediriger où tu veux : un terminal, un bot de messagerie, ou une pipeline CI qui commente tes pull requests. En un après-midi, tu passes d'utilisateur d'un agent à créateur d'un agent, et tu sais enfin ce qui se passe à chaque tour de la boucle.

Le CLI pi se personnalise via quatre mécanismes, tous logés dans de simples dossiers de ton projet ou de ton répertoire personnel :

• Extensions — des modules TypeScript qui enregistrent des outils, des commandes slash, des raccourcis clavier ou des éléments d'interface. Dépose le fichier dans le dossier extensions et il se charge au lancement. C'est là que tu écrirais un garde-fou de permissions, par exemple : une extension qui intercepte les commandes bash et demande confirmation avant les plus dangereuses.
• Skills — des paquets de capacités suivant le standard Agent Skills, le même popularisé par Anthropic, donc tes skills existants sont réutilisables tels quels.
• Prompts — des prompts réutilisables en simples fichiers markdown.
• Thèmes — rechargés à chaud pendant que le CLI tourne.

Tout ça s'installe comme n'importe quel paquet : pi install prend un paquet npm ou un dépôt git, et une seule commande met tout à jour. Les docs résument la philosophie en une phrase : adapte pi à tes workflows, pas l'inverse, sans forker ni patcher l'interne.

C'est l'inverse des gros harnais. Là où Claude Code embarque sub-agents, plan mode et permissions dans le produit, pi les laisse volontairement de côté, à construire en extension ou à installer depuis la communauté. Le pari est clair : un noyau minimal qui bouge à peine, et toute la personnalisation qui vit de ton côté, dans des fichiers versionnés avec ton projet.

La transparence de pi se paie en travail, et ce coût se décline en trois volets.

D'abord les garde-fous : par défaut, il n'y a aucune demande de permission intégrée, donc l'agent peut lancer une commande bash sans rien te demander. Les docs officielles l'assument et proposent trois patrons d'isolation, Docker inclus — mais les mettre en place avant de lâcher l'agent sur une machine qui compte, c'est à toi de le faire.

Ensuite la maturité : c'est du v0.84, pas du 1.0, avec une centaine d'issues ouvertes et certaines API encore marquées expérimentales, comme le client de session distant ajouté ces dernières semaines. Ce qui marche aujourd'hui peut casser à la release suivante ; c'est le prix normal d'un projet qui avance aussi vite.

Enfin, le temps. Chaque confort que Claude Code offre d'office — plan mode, sub-agents, permissions fines — est un projet que tu construis toi-même ici, ou un paquet communautaire que tu traques en espérant qu'il reste maintenu. L'écosystème d'extensions a un an : tu trouveras moins de paquets prêts que de trous à combler. Même l'installation t'a montré le niveau de vigilance requis, avec son flag --ignore-scripts, et tu devras le garder sur toute la chaîne. Si ton objectif est de livrer du code ce soir, pi va d'abord te ralentir avant de t'accélérer — ne remplace pas ton harnais principal cette semaine.

pi s'adresse aux développeurs qui construisent des produits avec des agents, pas juste avec un agent. Pour eux, c'est sans doute le meilleur investissement d'apprentissage du moment : installe le CLI, écris un agent de vingt lignes avec le SDK, et donne-lui un outil à toi. Fais ça et tu comprendras Claude Code mieux que la plupart de ses utilisateurs.

Si tu veux juste un assistant productif aujourd'hui, garde ton harnais intégré et reviens quand le 1.0 aura livré les garde-fous : la valeur de pi est dans la compréhension et le contrôle, pas dans le confort immédiat. Entre les deux se trouve un terrain sans risque — garde Claude Code pour ton travail, et pi comme banc d'essai pour comprendre ce que ton outil principal te cache.

À retenir : les harnais ne sont plus des boîtes noires. Les pièces sont sur la table, documentées, sous licence MIT. La prochaine fois qu'un agent t'impressionnera ou t'agacera, tu sauras exactement quelle pièce regarder.