Pi, le dispositif d’agent de codage minimaliste : extensions, compétences, sessions et sécurité
Pourquoi un petit ensemble de codage pour terminal, doté de quatre outils et d’un prompt système court, peut surpasser les agents riches en fonctionnalités : installation, modèles, arbres de session, extensions, compétences et environnement isolé.
Les outils de codage en terminal tels que Claude Code, Cursor et OpenCode font désormais partie intégrante de la journée de nombreux développeurs, surtout depuis que OpenAI a rendu le Codex CLI open source en avril. Pi, un outil de codage délibérément simple, naît d’une critique envers tous ces outils : ils changent constamment sous nos yeux.
La critique ne porte pas sur des bugs. Il s’agit du fait que l’outil évolue, ce qui entraîne des changements dans le comportement du modèle. Les ingénieurs souhaitent disposer d’outils sur lesquels ils peuvent compter. Les LLM eux-mêmes sont peu fiables, mais au moins les éléments qui les entourent peuvent être rendus déterministes, y compris les outils, les prompts système et tout ce qui y est injecté.
Claude Code et Codex intègrent beaucoup d’éléments dans le contexte sans les afficher dans l’interface, et ces ajouts cachés perturbent le flux de travail de manière subtile. Les mises à jour ont lieu une fois par jour, voire plusieurs fois par jour. Un flux de travail qui fonctionne parfaitement à neuf heures du matin peut se dégrader à dix heures et se comporter complètement différemment à trois heures, sans que le modèle ne change et avec seulement un changement d’outil. De nouvelles fonctionnalités apparaissent presque tous les mois, parmi lesquelles MCP, les sous-agents, le mode planification et l’exécution en arrière-plan, ce qui rend de plus en plus difficile de suivre ce qui se passe en coulisses.
La réponse de Pi est une règle de conception : s’il n’est pas nécessaire, on ne le développe pas. Les outils existants injectent du contexte de manière invisible, et les utilisateurs ne peuvent pas voir ce qui se passe. Telle était la motivation.
Qu’est-ce qui a inspiré le minimalisme ?
Avant de développer Pi, son créateur, Mario Zechner, a consulté le classement de Terminal Bench, où se distinguait un outil nommé Terminus. Cet outil fournit au modèle un seul outil, à savoir une interface vers une session tmux. Le LLM envoie des frappes de touche individuelles et lit les sorties ANSI provenant de tmux pour accomplir la tâche. Avec seulement cela, il se classe presque toujours parmi les trois meilleurs et occupe souvent la première place.
Cela souligne une intuition utile : les modèles sont aujourd’hui fortement entraînés grâce à l’apprentissage par renforcement, ce qui leur permet déjà de comprendre ce qu’est un outil de programmation et de ne pas avoir besoin de fonctionnalités supplémentaires complexes. Pi incarne cette idée en étant un outil minimaliste tout en étant extensible.
Qu’est-ce qui rend Pi différent ?
La caractéristique distinctive de Pi est ce qu’il omet, des fonctionnalités que d’autres agents de codage considèrent comme standard. Prenons MCP : il s’agit de se connecter à un serveur, et à chaque début de session, chaque définition d’outil inonde le contexte. Les outils en ligne de commande sont accompagnés de fichiers README, qui ne sont lus et exécutés que lorsque c’est nécessaire, il n’y a donc aucune raison de consommer constamment du contexte pour eux.
Ce qu’il possède que les autres n’ont pas
Pi a été conçu par soustraction, pourtant il dispose de capacités que Claude Code ne possède pas. Les extensions et les paquets s’installent avec quelques commandes seulement :
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
Mécanisme d’extension
Les extensions sont écrites en utilisant une API importée depuis le paquet Pi :
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
Une extension peut s’associer à des événements tels que les appels d’outils. Un exemple permet de se prémunir contre des commandes de shell dangereuses :
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command.includes("rm -rf")) {
const ok = await ctx.ui.confirm(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
1. Installation
L’installation ne nécessite qu’un seul commandement :
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Un script d’installation est une alternative :
curl -fsSL https://pi.dev/install.sh | sh
Il existe deux méthodes d’authentification. L’une utilise une clé API :
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
L’autre réutilise une abonnement que vous possédez déjà :
# Use an existing subscription
pi
/login # Select a provider
Avec /login, les abonnements existants tels qu’Anthropic Claude Pro ou Max, OpenAI ChatGPT Plus ou Pro (Codex) et GitHub Copilot peuvent être utilisés tel quel. La courbe d’apprentissage est très faible : installez-le, commencez à discuter avec lui, et c’est prêt à fonctionner.
2. Configuration du modèle
Pi prend en charge plus de 15 fournisseurs de LLM. Les principaux sont :
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
Changer de modèle au milieu d’une session est tout à fait normal :
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
Des fournisseurs personnalisés peuvent être ajoutés dans ~/.pi/agent/models.json. Toute API compatible avec OpenAI, Anthropic ou Google fonctionne simplement grâce à la configuration, et des serveurs routeurs tels que llama.cpp peuvent servir un modèle local. Le fait de « ne pas être lié à un fournisseur » est l’un des avantages que Pi met le plus en avant.
3. Gestion des sessions
Les sessions sont stockées sous forme de fichier JSONL à structure arborescente, dans ~/.pi/agent/sessions/, avec des champs id et parentId pour chaque message. Grâce à cette structure, un seul fichier permet de gérer toutes ces opérations :
pi -c # Continue the most recent session
pi -r # Select from previous sessions
La commande /tree est particulièrement intéressante. Vous pouvez revenir à n’importe quel point de la conversation et en partir pour créer de nouvelles branches. Toute l’histoire est stockée dans un seul fichier, ce qui permet de dire facilement « Je voulais reprendre là où j’en étais il y a une demi-heure » et de le faire réellement.
/compact résume les anciens messages afin de compresser le contexte. La compression automatique est activée par défaut, et si le contexte devient trop volumineux, le système se rétablit et tente à nouveau automatiquement.
4. Les extensions en détail
C’est ici que Pi montre vraiment à quoi il sert. La personnalisation se fait en quatre niveaux :
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
Les paquets provenant de npm ou de git sont gérés de cette manière :
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
Les extensions peuvent effectuer tout ce qui suit :
- Ajouter des outils personnalisés, y compris des alternatives aux outils intégrés.
- Créer des sous-agents et des modes de planification personnalisés.
- Imposer des contrôles d’accès et une protection des chemins.
- Ajouter des éléments d’interface tels qu’une ligne d’état, un en-tête et un pied de page.
- Créer des points de contrôle Git ou des commits automatiques.
- Intégrer des serveurs MCP.
- Exécuter Doom en attendant, si vous le souhaitez.
Le point central est que toutes les fonctionnalités que d’autres agents intégrent au produit, y compris les sous-agents, les modes de planification et les fenêtres de permissions, peuvent être créées sous forme d’extension. Ainsi, la philosophie est de garder le noyau minimal.
5. Compétences
Les compétences sont des ensembles de capacités écrites en Markdown. Conformément à la norme Agent Skills, un dossier contenant un fichier SKILL.md constitue une compétence.
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
```
```text ## Steps 1. Perform this action. 2. Then perform that action. ```
Une compétence peut être invoquée explicitement à l’aide de /skill:name, et l’agent la charge également de lui-même lorsque la tâche le justifie. Le choix de conception clé consiste à ce que les compétences n’entrent dans le contexte que lorsque c’est nécessaire. Plutôt que de mettre tout le contenu dans le prompt du système, elles s’activent au moment de leur utilisation, ce qui permet au prompt du système de rester autour d’un millier de tokens.
6. Pi Web, l’interface du navigateur
Il existe également une interface de navigateur appelée Pi Web :
npx @agegr/pi-web@latest
Ses principales fonctionnalités :
- Un espace de travail de session permettant de lister, reprendre, renommer et supprimer les conversations antérieures par projet.
- Deux façons de créer des branches : démarrer une nouvelle session à partir d’un message, ou faire un fork à l’intérieur de la session actuelle.
- Affichage des fichiers de projet et diffusion des différences Git.
- Changement de worktree Git.
- Connexion au fournisseur, paramétrage du modèle, du paquet et des compétences directement dans le navigateur.
Comme il partage les paramètres ~/.pi/agent ainsi que les fichiers de session avec la version en terminal, passer du navigateur au terminal se fait sans effort.
7. Mémoire
La mémoire s’avère être un concept simple. L’approche adoptée est que Pi n’a pas besoin d’une base de données de mémoire à long terme distincte. À la place, il existe trois mécanismes :
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
En d’autres termes, ce qui a été fait reste dans la session, tandis que ce que vous souhaitez conserver en mémoire se trouve dans AGENTS.md. Ajouter de la mémoire via une extension constitue également un cas d’usage courant dérivé.
8. Rester en sécurité
Le Pi ne dispose d’aucun environnement sandbox intégré. Les opérations de lecture, d’écriture, d’édition ainsi que les commandes bash s’exécutent avec les privilèges de la personne qui l’a lancé, et il en va de même pour les extensions. C’est intentionnel : un sandbox intégré partiel ne propose qu’une frontière apparemment sûre, c’est pourquoi la position officielle consiste à laisser l’isolation réelle au système d’exploitation ainsi qu’aux couches de conteneur ou de VM. Les dépôts non fiables et les exécutions non surveillées doivent avoir lieu dans un environnement isolé.
Une option consiste à placer l’ensemble de l’environnement Pi dans Docker, ce qui représente l’approche la plus simple :
# 1. Put the entire pi environment in Docker (simplest)
Une autre solution consiste à exécuter Pi sur l’hôte et à diriger uniquement l’exécution des outils vers une micro-VM locale :
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
Une fonctionnalité appelée project trust ajoute une protection d’entrée. Elle empêche les dépôts de remplacer silencieusement les paramètres ou extensions de Pi, et par défaut demande une confirmation pour les projets non vérifiés. Cependant, elle ne prévient pas complètement l’injection de commandes, il convient donc de le garder à l’esprit lors du travail avec du code ou des documents inconnus.
9. Créer sa propre extension
L’extension la plus simple se compose d’un seul fichier TypeScript. Celui-ci enregistre un outil :
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
et il peut ajouter des commandes ou intercepter les appels d’outils :
pi.registerCommand("stats", {
// Custom command definition }); pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
Placez le fichier dans ~/.pi/agent/extensions/ pour tous les projets, ou dans .pi/extensions/ pour un seul projet ; il s’chargera automatiquement lorsque Pi démarre. Pour un test ponctuel, utilisez pi -e ./my-ext.ts. Le dépôt officiel propose de nombreux exemples : commits automatiques, points de contrôle Git, intégration MCP et compression personnalisée. Sur Pi, l’absence d’une fonctionnalité est normale. La démarche habituelle consiste à l’ajouter soi-même ou à installer un paquet.
Ce que Pi enseigne
Pour quiconque crée son propre agent, les choix de Pi constituent une référence utile. Évitez les paquets tout-en-un. Commencez avec quatre outils et un prompt système d’environ mille tokens, puis n’ajoutez que ce qui est nécessaire. La conception commence par déterminer ce qui doit être supprimé, et non par ce qui doit être ajouté.
Lectures complémentaires
- Les cinq couches d’un agent harness, avec du code qui échoue en l’absence de celles-ci — Une présentation pratique des cinq endroits où un agent harness applique des règles dans le code, des limites d’exécution aux pipelines de contexte, ainsi de ce que la recherche peut et ne peut pas prouver.
- Notes pratiques : Construire un agent de codage en cloud privé : OpenCode + un LLM local — Guide opérationnel des Notes pratiques : Construire un agent de codage en cloud privé : OpenCode + un LLM local : contrats, vérifications et emplacements de code à insérer pour les équipes qui utilisent ce modèle.