Ce que j’ai appris en construisant l’agent de codage Pi

• pi-coding-agent est un framework d’agent de codage conçu pour minimiser les fonctionnalités complexes et permettre à l’utilisateur de garder un contrôle total du contexte et de la transparence
• Les quatre composants clés sont pi-ai, pi-agent-core, pi-tui et pi-coding-agent, chacun prenant en charge respectivement l’intégration d’API LLM, la boucle d’agent, l’interface terminal et l’intégration CLI
• Le système vise une simplification extrême en maintenant le prompt système et l’ensemble d’outils sous 1000 tokens, avec seulement quatre outils : read/write/edit/bash
• Il écarte entièrement les restrictions de sécurité, sous-agents, mode plan et support MCP, en privilégiant à la place une observabilité complète et le contrôle
• Les résultats de benchmark et l’expérience d’usage réelle montrent qu’une conception simple et transparente peut être tout à fait compétitive face à des agents plus complexes

---

pi-ai et pi-agent-core

• pi-ai fournit une API d’intégration unifiée pour différents fournisseurs de LLM comme Anthropic, OpenAI, Google, xAI et Groq
  • Inclut le streaming, les appels d’outils, la prise en charge du raisonnement (trace), le suivi des tokens et des coûts, ainsi que la compatibilité navigateur
  • Quatre API majeures seulement (OpenAI Completions/Responses, Anthropic Messages, Google Generative AI) suffisent pour communiquer avec la plupart des modèles
• Les différences d’API entre fournisseurs sont unifiées et gérées de façon cohérente
  • Ex. : différences de nom de champ max_tokens, emplacement du champ reasoning, absence de prise en charge du rôle developer, etc.
  • Comme les modes de remontée des tokens varient fortement, un calcul exact des coûts est impossible ; pi-ai effectue donc un suivi en mode best-effort
• La fonction de context handoff permet de changer de modèle ou de fournisseur en cours de session
  • Ex. : lors d’un passage d’Anthropic → OpenAI → Google, le contenu de raisonnement est conservé en étant converti en balises ``
• Un registre de modèles permet des définitions de modèles sûres du point de vue des types
  • Les données d’OpenRouter et de models.dev sont analysées afin de générer automatiquement les informations de coût et de capacités par modèle
• La gestion de l’interruption des requêtes (abort) et le retour de résultats partiels sont entièrement pris en charge
  • Si le streaming est interrompu via AbortController, les résultats intermédiaires peuvent être utilisés tels quels
• Une structure séparée pour les résultats d’outils a été introduite
  • Le texte destiné au LLM et les données destinées à l’affichage UI sont renvoyés séparément, avec validation des arguments via TypeBox/AJV
  • Une fonction de streaming des résultats d’outils est prévue pour plus tard
• La boucle d’agent répète automatiquement le traitement des messages, l’exécution des outils et le retour des résultats
  • Une structure orientée événements facilite la création d’interfaces réactives
  • Les paramètres de contrôle inutiles (nombre maximal d’étapes, etc.) ont été retirés pour simplifier l’ensemble

pi-tui

• pi-tui est un framework d’interface terminal basé sur Node.js, qui prend en charge les mises à jour en temps réel avec un minimum de flicker
  • Le rendu différentiel (differential rendering) ne met à jour que les lignes modifiées
  • Les séquences de sortie synchronisées (CSI ?2026h/l) réduisent le flicker au minimum
• Parmi deux approches TUI, le projet adopte un mode de sortie de type CLI qui conserve le tampon de scrollback
  • Les fonctions natives du terminal comme le défilement naturel et la recherche restent disponibles telles quelles
  • Structure similaire à Claude Code, Codex et Droid
• Il utilise une UI en retained mode
  • Chaque composant met en cache son propre rendu et ne se redessine qu’en cas de changement
  • Cela permet des mises à jour efficaces sans rerendu complet de l’écran
• Les performances et l’usage mémoire restent minimes ; même de grandes sessions se traitent aisément avec quelques centaines de Ko

pi-coding-agent

• pi-coding-agent est un agent de codage en CLI qui fournit les fonctions suivantes
  • Prise en charge de Windows/Linux/macOS, gestion de session (reprise et branchement), changement de modèle, chargement de AGENTS.md par projet
  • Authentification OAuth, changement de thème en temps réel, export de session en HTML, prise en charge du mode headless (JSON/RPC)
• Le prompt système reste concis avec moins de 1000 tokens
  • Il ne mentionne que les quatre outils read/write/edit/bash
  • Les explications inutiles et les règles complexes sont supprimées ; l’utilisateur peut étendre librement via AGENTS.md
• L’ensemble d’outils se limite à 4 outils minimum
  • Seuls read, write, edit et bash sont utilisés, ce qui suffit pour la plupart des tâches de codage
  • Des outils supplémentaires peuvent être activés en option (ex. : grep, find, ls)
• Le mode YOLO est appliqué par défaut
  • Aucun blocage sur l’accès à l’ensemble du système de fichiers ni sur l’exécution de commandes
  • Les prompts de sécurité et procédures de validation préalable sont supprimés ; l’usage en environnement conteneurisé est recommandé à la place
• Les fonctions To-do intégré, mode Plan, MCP, Background bash et Sub-agent sont toutes supprimées
  • To-do/Plan sont simplement remplacés par une gestion basée sur des fichiers (TODO.md, PLAN.md)
  • MCP est exclu à cause du gaspillage de tokens et de la complexité, et remplacé par une approche CLI + README
  • Pour Background bash, l’usage de tmux est recommandé
  • Les Sub-agents sont désactivés faute de visibilité ; si nécessaire, l’agent peut s’appeler lui-même via bash
• L’accent est mis sur l’observabilité (Observability)
  • Toutes les commandes, tous les accès fichiers et toutes les sorties sont affichés de façon transparente
  • En contraste avec la structure en « boîte noire » d’autres agents comme Claude Code

Benchmarks

• Des tests ont été réalisés sur Terminal-Bench 2.0 avec le modèle Claude Opus 4.5
  • Des performances compétitives ont été obtenues face à Codex, Cursor, Windsurf, etc.
  • Le fichier de résultats (results.json) a été soumis au dépôt public
• Des agents simples comme Terminus 2 montrent aussi des performances comparables, ce qui valide l’approche minimaliste

Conclusion

• pi est un agent de codage qui privilégie le contrôle du contexte, la simplicité et la transparence plutôt que les fonctionnalités complexes
• Tant dans l’usage réel que dans les benchmarks, il montre une efficacité équivalente à celle de grands agents
• Les principales fonctionnalités prévues pour la suite sont la compaction du contexte et le streaming des résultats d’outils
• Le projet est publié en open source, avec liberté de fork et d’extension garantie
• La leçon essentielle est que « la simplicité est le contrôle, et le contrôle est la productivité »