Le Guide Complet de Pi

mai 2026 · 12 min de lecture

Coder avec une IA dans ton terminal — installation, configuration et personnalisation

Salut, et merci d'avoir commenté sous la vidéo. Voici le guide promis.

Tu vas apprendre à installer Pi, à le brancher sur des modèles d'IA (y compris gratuits), et à le transformer en ton outil de code sur-mesure. Tout est expliqué pas à pas. Aucune connaissance préalable en ligne de commande n'est obligatoire, mais quelques bases aident.

Prends 20 minutes, suis le guide dans l'ordre, et tu auras un agent de code fonctionnel à la fin.

Sommaire

C'est quoi Pi, et pourquoi l'utiliser
Ce dont tu as besoin avant de commencer
Installer Pi
Connecter une IA à Pi
- Option A — Modèles gratuits avec OpenRouter (recommandé pour débuter)
- Option B — Ton abonnement existant (Claude, ChatGPT, Copilot)
- Option C — Une clé API classique
Ta première session
Donner des instructions à Pi avec AGENTS.md
Les commandes et raccourcis à connaître
Personnaliser Pi : le vrai intérêt de l'outil
Problèmes fréquents et solutions
Pour aller plus loin

1. C'est quoi Pi, et pourquoi l'utiliser

Pi est un agent de code qui vit dans ton terminal. Tu lui écris ce que tu veux en français ou en anglais, et il lit tes fichiers, écrit du code, lance des commandes et modifie ton projet.

Trois choses le distinguent des autres outils du même genre :

C'est gratuit et open-source. Le code est public, sous licence MIT. Tu peux l'utiliser sans payer l'outil lui-même. Tu paies seulement l'IA derrière, et encore, pas toujours (voir l'option OpenRouter plus bas).

Tu choisis ton IA. Pi se branche sur plus de 15 fournisseurs : Anthropic, OpenAI, Google, Mistral, OpenRouter, et d'autres. Tu changes de modèle en pleine session avec un raccourci.

Il se personnalise. Pi est volontairement minimaliste. Si une fonctionnalité te manque, tu peux demander à Pi de se la coder lui-même, ou installer un module tout fait. C'est l'idée centrale de l'outil : tu l'adaptes à ta façon de travailler, pas l'inverse.

Une précision honnête : Pi est un outil de terminal. Si tu n'as jamais ouvert un terminal de ta vie, ce guide reste faisable, mais prends ton temps sur les premières étapes.

2. Ce dont tu as besoin avant de commencer

Avant d'installer Pi, il te faut Node.js sur ta machine. C'est le moteur qui fait tourner Pi.

Pour vérifier si tu l'as déjà, ouvre ton terminal et tape :

node --version

Si un numéro s'affiche (par exemple v20.11.0), tu es bon. Si tu vois une erreur du type « command not found », installe Node.js depuis le site officiel : https://nodejs.org — prends la version « LTS ».

Où trouver le terminal ?

Windows : cherche « PowerShell » dans le menu Démarrer.
macOS : cherche « Terminal » dans Spotlight (Cmd + Espace).
Linux : tu sais déjà.

Garde cette fenêtre ouverte, tu vas en avoir besoin tout le long.

3. Installer Pi

Il y a deux méthodes. Choisis-en une.

Méthode 1 — La commande universelle (fonctionne partout)

Colle ceci dans ton terminal et appuie sur Entrée :

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

L'option --ignore-scripts est une mesure de sécurité : elle empêche l'exécution de scripts pendant l'installation. Pi n'en a pas besoin pour fonctionner normalement.

Méthode 2 — L'installeur rapide (macOS et Linux uniquement)

curl -fsSL https://pi.dev/install.sh | sh

Une fois l'installation terminée, vérifie que tout est en place. Place-toi dans le dossier d'un projet, puis lance Pi :

cd /chemin/vers/ton/projet
pi

Si une interface s'ouvre dans le terminal, l'installation est réussie. Pi ne fonctionnera pas encore tant que tu ne lui as pas connecté une IA — c'est l'étape suivante.

Pour désinstaller Pi plus tard : npm uninstall -g @earendil-works/pi-coding-agent

4. Connecter une IA à Pi

Pi a besoin d'un « cerveau » : un modèle d'intelligence artificielle. Tu as trois options. Si tu débutes, va directement à l'option A.

Option A — Modèles gratuits avec OpenRouter (recommandé pour débuter)

OpenRouter est un service qui regroupe des centaines de modèles d'IA derrière une seule clé. Et plusieurs de ces modèles sont gratuits. C'est la meilleure porte d'entrée pour tester Pi sans sortir la carte bancaire.

Étape 1 — Crée un compte OpenRouter

Va sur https://openrouter.ai et inscris-toi. C'est gratuit.

Étape 2 — Génère ta clé API

Dans les paramètres de ton compte OpenRouter, va dans la section « Keys » et crée une nouvelle clé. Copie-la, elle ressemble à une longue suite de caractères. Garde-la pour toi : c'est une clé personnelle.

Étape 3 — Donne la clé à Pi

Tu dois enregistrer cette clé dans une variable d'environnement nommée OPENROUTER_API_KEY.

Sur macOS / Linux, dans ton terminal :

export OPENROUTER_API_KEY=colle-ta-clé-ici

Sur Windows (PowerShell) :

$env:OPENROUTER_API_KEY="colle-ta-clé-ici"

Attention : cette commande ne vaut que pour la fenêtre de terminal actuelle. Pour la rendre permanente, ajoute la ligne export à ton fichier ~/.bashrc ou ~/.zshrc (macOS/Linux). Si ce paragraphe te semble obscur, ignore-le pour l'instant : retape simplement la commande à chaque fois que tu ouvres un nouveau terminal.

Étape 4 — Lance Pi et choisis un modèle gratuit

Démarre Pi avec pi, puis tape /model pour ouvrir la liste des modèles. Cherche ceux dont le nom contient « free » — ce sont les gratuits. La liste complète est ici : https://openrouter.ai/collections/free-models

À savoir : les modèles gratuits ont des limites d'usage (nombre de requêtes par jour) et sont parfois plus lents. C'est parfait pour apprendre et tester. Pour du travail intensif, tu passeras plus tard sur un modèle payant.

Option B — Ton abonnement existant (Claude, ChatGPT, Copilot)

Si tu as déjà un abonnement Claude Pro/Max, ChatGPT Plus/Pro ou GitHub Copilot, tu peux t'en servir directement.

Lance Pi, puis tape :

/login

Sélectionne ton fournisseur dans la liste et suis la procédure de connexion. Tes identifiants sont stockés localement et se renouvellent automatiquement.

Note importante pour Claude Pro/Max : l'usage via un outil tiers comme Pi est facturé au token sur ton crédit « extra usage », et non décompté de ton forfait Claude habituel. Surveille ta consommation.

Option C — Une clé API classique

Si tu as une clé API directe chez un fournisseur (Anthropic, OpenAI, Google, Mistral…), enregistre-la dans la variable d'environnement correspondante avant de lancer Pi.

Quelques exemples :

export ANTHROPIC_API_KEY=sk-ant-...      # pour Claude
export OPENAI_API_KEY=sk-...             # pour les modèles OpenAI
export GEMINI_API_KEY=...                # pour Google Gemini
export MISTRAL_API_KEY=...               # pour Mistral

Tu peux aussi utiliser /login à l'intérieur de Pi et choisir le fournisseur correspondant : la clé sera stockée dans le fichier ~/.pi/agent/auth.json.

5. Ta première session

Tout est branché ? Place-toi dans un dossier de projet et lance Pi :

cd /chemin/vers/ton/projet
pi

Écris ta demande en langage normal et appuie sur Entrée. Par exemple :

Résume ce projet et explique-moi comment lancer les tests.

Pi va lire tes fichiers et te répondre.

Pour faire son travail, Pi dispose par défaut de quatre outils :

read — lire des fichiers
write — créer ou remplacer des fichiers
edit — modifier des fichiers existants
bash — exécuter des commandes dans le terminal

Pi travaille directement dans ton dossier courant et peut donc modifier tes fichiers. Conseil de sécurité essentiel : utilise Git sur ton projet. Comme ça, si Pi fait une bêtise, tu peux tout annuler avec un simple retour en arrière. Ne lance pas Pi sur un dossier important sans sauvegarde.

6. Donner des instructions à Pi avec `AGENTS.md`

C'est ici que Pi devient vraiment utile. Tu peux lui donner des règles permanentes via un fichier texte appelé AGENTS.md, placé à la racine de ton projet.

Crée le fichier AGENTS.md et écris dedans tes consignes, en français ou en anglais. Exemple :

# Instructions du projet

- Lance `npm run check` après chaque modification de code.
- Réponds toujours en français.
- Garde les réponses courtes et précises.
- Ne touche jamais aux fichiers du dossier /production.

Pi lit ce fichier au démarrage. Il charge aussi :

~/.pi/agent/AGENTS.md — tes instructions globales, valables pour tous tes projets
les fichiers AGENTS.md ou CLAUDE.md présents dans le dossier courant et les dossiers parents

Après avoir modifié un de ces fichiers, tape /reload dans Pi ou redémarre-le pour qu'il prenne en compte les changements.

C'est un réflexe à prendre : chaque fois que Pi se trompe de façon récurrente, ajoute une règle dans AGENTS.md au lieu de le corriger à chaque fois.

7. Les commandes et raccourcis à connaître

Voici l'essentiel pour être à l'aise rapidement.

Les commandes (tape / suivi du nom)

Commande	Ce qu'elle fait
`/login`	Se connecter à un fournisseur d'IA
`/model`	Choisir le modèle d'IA à utiliser
`/reload`	Recharger la config après une modification
`/new`	Démarrer une nouvelle session vierge
`/resume`	Reprendre une session précédente
`/tree`	Naviguer dans l'arbre de la session
`/share`	Partager ta session via un lien
`/export`	Exporter la session en fichier HTML

Les raccourcis clavier

Raccourci	Action
`Ctrl+L`	Changer de modèle rapidement
`Ctrl+P`	Faire défiler tes modèles favoris
`Shift+Tab`	Changer le niveau de réflexion du modèle
`Entrée`	Envoyer un message (oriente l'agent en cours de route)
`Alt+Entrée`	Mettre un message en file d'attente pour après

Deux astuces pratiques

Tape @ dans l'éditeur pour chercher et insérer un fichier de ton projet dans ta demande.

Commence une ligne par ! pour lancer une commande shell directement, par exemple !npm run lint. Le résultat est transmis à l'IA.

Reprendre le travail plus tard

Tes sessions sont sauvegardées automatiquement. Pour les retrouver :

pi -c                  # reprendre la dernière session
pi -r                  # parcourir les sessions précédentes

8. Personnaliser Pi : le vrai intérêt de l'outil

Pi est livré minimaliste volontairement. Il n'a pas de sous-agents, pas de mode plan, pas de système de permissions intégré. Ce ne sont pas des oublis : l'idée est que tu construises seulement ce dont tu as besoin.

Tu as trois façons de personnaliser Pi.

1. Demander à Pi de se modifier lui-même

C'est la méthode la plus simple, et la plus impressionnante. Tu peux littéralement demander à Pi d'ajouter une fonctionnalité, et il va écrire le code qui le modifie.

Exemple de demande, directement dans Pi :

Crée-moi une commande /commit qui résume mes changements et prépare un message de commit propre.

Pi écrit l'extension, tu tapes /reload, et ta nouvelle commande existe. Pas de plugin à télécharger, pas d'attente.

2. Installer des packages tout faits

La communauté partage des modules prêts à l'emploi : sous-agents, mode plan, protections de fichiers, et bien d'autres. Tu les installes depuis npm ou GitHub :

pi install npm:@nom-du-package

Parcours les packages disponibles ici : https://pi.dev/packages

3. Écrire tes propres extensions

Pour les plus à l'aise, une extension Pi est un module TypeScript. Tu as accès aux outils, aux commandes, aux raccourcis clavier, aux événements et à toute l'interface du terminal. C'est ce qui permet de construire absolument tout ce que les autres agents imposent en dur.

Les autres leviers de personnalisation

Skills — des capacités réutilisables que Pi charge à la demande seulement quand il en a besoin.
Prompt templates — des prompts réutilisables écrits en Markdown. Tu tapes /nom pour les déclencher.
Themes — change l'apparence du terminal. Plusieurs thèmes intégrés, et tu peux créer les tiens.
SYSTEM.md — remplace ou complète le prompt système par défaut, projet par projet.

Tu n'as pas besoin de tout maîtriser tout de suite. Commence par AGENTS.md et la méthode « demande à Pi de se modifier ». Le reste viendra quand tu en ressentiras le besoin.

9. Problèmes fréquents et solutions

« command not found: pi » après l'installation Le terminal ne trouve pas Pi. Ferme complètement ta fenêtre de terminal et rouvres-en une nouvelle. Si le problème persiste, vérifie que Node.js est bien installé avec node --version.

« command not found: npm » Node.js n'est pas installé. Va sur https://nodejs.org et installe la version LTS.

Pi se lance mais répond par une erreur d'authentification Aucune IA n'est connectée, ou ta clé est invalide. Reprends l'étape 4. Vérifie que ta variable d'environnement est bien définie dans la fenêtre de terminal que tu utilises.

Ma clé API « disparaît » quand je rouvre le terminal C'est normal : la commande export ne vaut que pour la session en cours. Soit tu la retapes à chaque fois, soit tu l'ajoutes à ton fichier ~/.bashrc ou ~/.zshrc pour la rendre permanente.

Le modèle gratuit refuse de répondre ou est très lent Les modèles gratuits d'OpenRouter ont des limites quotidiennes. Attends un peu, ou passe sur un autre modèle gratuit avec /model.

« model not supported » avec GitHub Copilot Active le modèle dans VS Code : Copilot Chat → sélecteur de modèle → choisis le modèle → « Enable ».

10. Pour aller plus loin

Site officiel : https://pi.dev
Documentation complète : https://pi.dev/docs/latest
Modèles gratuits OpenRouter : https://openrouter.ai/collections/free-models
Packages de la communauté : https://pi.dev/packages
Code source (GitHub) : https://github.com/earendil-works/pi
Serveur Discord : pour poser tes questions et échanger avec d'autres utilisateurs

Voilà, tu as tout pour démarrer. Le meilleur conseil que je puisse te donner : ne reste pas à lire. Installe Pi, lance-le sur un petit projet de test, et joue avec. C'est en l'utilisant que tu comprendras ce que tu peux en tirer.

Si ce guide t'a aidé, dis-le moi en commentaire — ça me motive à en faire d'autres.

Bon code.