Ma Stack Pi Coding Agent • FRFlo

L’émergence des assistants de développement pilotés par des LLMs (Large Language Models) a profondément transformé notre façon de concevoir, prototyper et maintenir du code. Pourtant, la majorité des solutions du marché (extensions d’IDEs, applications propriétaires en sandbox fermée ou simples clients CLI) imposent des compromis majeurs : contextes éphémères qui s’évaporent à la fin d’une session, exécution séquentielle bloquante, incapacité à interagir avec le monde extérieur de manière asynchrone, et absence de contrôle sur la sécurité des commandes exécutées.

Pour dépasser ces limites, j’ai construit un écosystème sur-mesure articulé autour de Pi Coding Agent (@earendil-works/pi-coding-agent), un agent de développement modulaire et extensible écrit en TypeScript.

Cette stack ne se contente pas d’exécuter de simples commandes bash ou de modifier des fichiers texte. Elle intègre un moteur de mémoire persistante SQLite à double modèle, un système de sous-agents natifs capables d’opérer en parallèle sans bloquer la boucle principale, un bridge Discord bidirectionnel pour le pilotage distant sur mobile, une passerelle MCP avancée connectée à mon infrastructure Zero Trust, une sécurisation proactive des commandes système, et plusieurs providers (OpenAI Codex, Antigravity et recherche Web) avec raisonnement (thinking models) et génération d’images.

Voici le deep dive technique complet de cette architecture.

Vue d’ensemble de l’Architecture

L’architecture globale de ma stack Pi s’organise en couches interconnectées garantissant une séparation stricte entre le runtime d’orchestration, les extensions métier, les moteurs de stockage et les interfaces externes :

flowchart TB
    subgraph UI["Interfaces Utilisateur & Contrôle Distant"]
        TUI["Pi TUI (Terminal Interactif)"]
        Discord["Discord Mobile / Desktop<br>Boutons Interactifs & Webhooks"]
    end

    subgraph Runtime["Cœur Pi Coding Agent (TypeScript / Node.js)"]
        Core["Orchestrateur Pi & State Machine"]
        ExtLoader["Loader d'Extensions & Packages"]
        ToolManager["Tool Registry & Guardrails"]
    end

    subgraph LLMProviders["Couche LLMs & Providers"]
        Antigravity["pi-antigravity (OAuth Google Cloud Code)<br>Gemini 3.7 / 3.8 Flash Thinking"]
        Quotas["pi-quotas (Rate Limits & Token Trackers)"]
    end

    subgraph Parallelism["Exécution Parallèle & Multiplexage"]
        Subagents["interactive-subagents (AgentSession natifs)<br>Sessions isolées & Steer callbacks"]
        PTYManager["terminal manager (Persistent PTY)<br>Sessions d'arrière-plan & Monitor regex"]
    end

    subgraph MemoryLayer["Mémoire Persistante Long-Terme"]
        SQLiteDB[("observational-memory.sqlite<br>Ledger de branches & Compaction")]
        Observer["Observer Model (Headless Pi)<br>Extraction d'observations atomiques"]
        Consolidator["Consolidator Model<br>Indexation thématique .memory/"]
    end

    subgraph SecurityExt["Sécurité & Outils Locaux"]
        BashGuard["bash-guard (Interception L7 & Confirmation)"]
        MoveTool["move-tool (AST Relocation & Rollback)"]
        TodoTool["pi-todotools (State machine par phases)"]
        SearchTools["pi-web-search & Gemini URL Context"]
    end

    subgraph MCPLayer["Passerelle MCP (pi-mcp-adapter)"]
        MCPEngine["MCP Client Gateway & mcpScript Runtime"]
        CFAPI["Cloudflare API & Browser MCP"]
        Context7["Context7 (Docs temps réel)"]
        GrepApp["Grep.app (GitHub Code Search)"]
        GitHubMCP["GitHub Copilot MCP (OAuth)"]
    end

    UI <--> Runtime
    Runtime --> LLMProviders
    Runtime --> Parallelism
    Runtime --> MemoryLayer
    Runtime --> SecurityExt
    Runtime --> MCPLayer
    Discord <-->|"pi-bridge (HTTPS / Webhooks)"| Runtime

1. Le Moteur de Modèles : `pi-antigravity` & `pi-quotas`

Le cœur d’un agent de développement réside dans la pertinence de ses modèles de langage et la fiabilité de sa couche de communication API.

`pi-antigravity` : L’intégration Google Cloud Code

Plutôt que de dépendre d’un seul endpoint, j’utilise plusieurs providers selon la tâche. pi-antigravity implémente l’authentification OAuth directe avec les services Google Antigravity / Cloud Code, tandis que mon profil local utilise actuellement OpenAI Codex comme modèle par défaut. Les préférences privées restent séparées de la configuration partageable.

{
  "defaultProvider": "openai-codex",
  "defaultModel": "gpt-5.6-luna",
  "packages": [
    "npm:pi-antigravity",
    "npm:pi-mcp-adapter",
    "git:github.com/FRFlo/pi-quotas",
    "git:github.com/FRFlo/pi-web-search",
    "git:github.com/FRFlo/pi-interactive-subagents"
  ]
}

Cette intégration offre plusieurs avantages clés :

Accès natif aux Thinking Models : Support transparent des modèles Gemini disponibles dans le catalogue Antigravity, avec configuration du niveau de réflexion (thinking level : off, low, medium, high, max).
Génération d’images intégrée (generate_image) : Possibilité pour l’agent de concevoir des maquettes graphiques, assets ou schémas directement via les modèles Imagen / Gemini sans quitter le cycle de dev.
Gestion automatique des jetons OAuth : Rafraîchissement transparent des credentials sans nécessiter d’injections manuelles de clés d’API dans l’environnement shell.

`pi-quotas` : Surveillance temps réel des limites de consommation

Développé sur-mesure pour ma stack, le package pi-quotas se greffe aux hooks du cycle de vie de Pi pour afficher les quotas Antigravity réels, les compteurs de tokens et le délai avant réinitialisation. Il permet d’anticiper les dépassements de seuil et d’éviter les interruptions brutales lors de sessions de refactoring intensives.

2. Mémoire Persistante Long-Terme : `observational-memory`

L’un des problèmes majeurs des agents IA classiques est l’amnésie de contexte : au fur et à mesure que la conversation s’allonge, le context window s’engorge, forçant une troncation destructrice ou un résumé naïf qui élimine les décisions d’architecture critiques.

Pour résoudre ce problème de manière déterministe, ma stack intègre l’extension Observational Memory, une architecture de mémoire hiérarchisée basée sur SQLite.

flowchart LR
    A["Chunks de conversation<br/><i>Découpage par tokens fixes</i>"] --> B["Observers parallèles<br/><i>Instances pi headless</i>"]
    B --> C["Observations atomiques<br/><i>{timestamp, contenu, contexte}</i>"]
    C --> D["Master Ledger SQLite<br/><i>observational-memory.sqlite</i>"]
    D --> E["Compaction Déterministe<br/><i>Sans appel LLM (zero hallucination)</i>"]
    D --> F["Consolidator Model<br/><i>gemini-3.7-flash dédié</i>"]
    F --> G[".memory/&lt;session&gt;/&lt;topic&gt;.md<br/><i>Fichiers Markdown pérennes</i>"]

Fonctionnement du double modèle (Observer / Consolidator)

L’Observer (Observateur Asynchrone) : En tâche de fond, des sous-processus légers analysent les blocs récents de la conversation. Ils en extraisent des observations atomiques (faits, préférences de style, décisions de conception, corrections d’erreurs).
Le Master Ledger SQLite : Toutes les observations sont inscrites dans une base SQLite locale (observational-memory.sqlite). Cette structure est compatible avec l’arbre d’état de Pi (/tree), garantissant que si une session bifurque ou revient en arrière, la mémoire reste fidèle à la branche active.
La Compaction Déterministe : Contrairement aux approches conventionnelles où un LLM résume le contexte (avec le risque d’inventer ou de perdre des détails), la compaction de Pi compile les observations vérifiées directement dans le bloc de contexte système.
Le Consolidator (Consolidation Thématique) : Périodiquement, le modèle consolidateur regroupe les observations les plus anciennes pour les archiver sous forme de fichiers Markdown structurés dans le répertoire .memory/<sessionId>/. Ces fichiers sont directement indexés et interrogeables via des recherches rapides.

3. Sous-Agents Natifs & Asynchrones : `pi-interactive-subagents`

Les tâches de développement complexes exigent souvent de mener de front plusieurs chantiers : explorer une documentation technique, auditer des logs de build, exécuter des tests de non-régression et coder une fonctionnalité.

Le package pi-interactive-subagents permet de lancer des agents secondaires entièrement autonomes sans jamais bloquer l’agent principal. Depuis la dernière version de cette stack, les sous-agents ne reposent plus sur un backend tmux/psmux : chaque enfant s’exécute comme une instance native de AgentSession dans le processus Pi.

╭─ Subagents ──────────────────────────── 2 running ─╮
│ 00:23  scout      active · bash 7m                 │
│ 00:45  worker-1   waiting 2m                       │
╰────────────────────────────────────────────────────╯

Mécanisme technique : sessions natives et isolation

Spawn non-bloquant : subagent({ agent: "scout", task: "..." }) crée une session Pi indépendante et rend immédiatement la main à l’orchestrateur.
Retour événementiel : il n’y a plus de polling ni de fichiers temporaires à surveiller. À la fin de son tour, le résultat est injecté dans la session par un événement steer.
Isolation par allowlist : chaque profil d’agent reçoit uniquement les outils, extensions, skills et modèles déclarés dans son frontmatter. Cette restriction est conservée lors d’une reprise.
Reprise persistante : le registre associe chaque nom à son transcript et un snapshot de loadout permet de reprendre exactement le même environnement, y compris pour les sous-agents imbriqués.
Contrôle bidirectionnel : l’agent principal peut envoyer de nouvelles directives à un sous-agent en cours d’exécution ou relancer une session terminée via subagent_message.

4. Supervision Distante & Bridge Discord Mobile

Pour garder le contrôle sur des tâches d’automatisation longues lorsque je ne suis pas devant mon poste de travail, la stack intègre un bridge Discord bidirectionnel temps réel.

sequenceDiagram
    participant Pi as Pi Coding Agent
    participant Bridge as pi-bridge (API)
    participant Discord as Discord Client (Mobile/Web)

    Pi->>Bridge: POST /ask (Question + Choix + Recent Turn)
    Bridge->>Discord: Message Embed + Boutons ActionRow
    Note over Discord: L'utilisateur clique sur une option<br/>ou tape une réponse libre
    Discord->>Bridge: Interaction Webhook (Component Click / Modal)
    Bridge-->>Pi: Réponse HTTP résolue (Option choisie / Texte)
    Pi->>Pi: Reprise immédiate du flux de travail

L’extension `ask-user-question` et son TUI réactif

Lorsqu’un choix d’architecture ou une confirmation est requis, l’outil ask_user_question s’adapte dynamiquement à l’environnement :

En mode TUI interactif : Affichage d’un menu déroulant ANSI navigable au clavier (touches fléchées, barre d’espace pour multi-sélection, champ de saisie libre).
Synchronisation Discord instantanée : En parallèle, le payload est transmis au service pi-bridge. Une interface riche avec des boutons interactifs apparaît sur Discord. Que je réponde depuis mon terminal ou depuis mon smartphone, l’interaction est résolue instantanément.
Questions persistantes et rapports proactifs : ask_user_question n’expire plus automatiquement. Une question peut rester ouverte jusqu’à une réponse depuis le TUI ou Discord, tandis que send_discord_message transmet les fins de build, alertes de régression et synthèses de déploiement en Markdown riche.

5. Terminal Persistant & Sécurité Active : `terminal` & `bash-guard`

La manipulation du système hôte par un agent IA comporte des risques majeurs : commandes destructrices accidentelles, processus d’arrière-plan fantômes et surcharge mémoire.

Terminal persistant PTY et pattern `monitor`

L’extension terminal dote Pi d’un gestionnaire de sessions PTY (pseudo-terminal) complètes :

Sessions en tâche de fond : Lancement de serveurs dev, conteneurs ou builds sans bloquer le REPL.
Souscription d’événements (monitor) : Au lieu de scruter passivement un log, l’agent s’abonne à des expressions régulières spécifiques (ex: READY, Compiled successfully, ERROR). L’agent est notifié dès que la condition est satisfaite.
Pilotage de REPLs interactifs : Envoi de frappes de touches et de signaux (ctrl+c, bash_input, bash_resize).

`bash-guard` : L’intercepteur de sécurité L7

Pour prémunir le système contre toute fausse manipulation, chaque commande shell est soumise au filtre de bash-guard :

Analyse syntaxique préventive : Détection des motifs à risque (rm -rf /, mkfs, écrasement de disques, commandes avec élévation de privilèges imprévue).
Floor de confirmation : En cas de doute, la commande est mise en pause et nécessite une validation explicite de l’utilisateur (via le TUI ou le bridge Discord).

6. La Passerelle MCP (`pi-mcp-adapter`) : La Hiérarchie des Outils Clés

Le standard MCP (Model Context Protocol) permet d’étendre les capacités de l’agent vers des services tiers. Grâce au package pi-mcp-adapter, Pi se connecte à un réseau de serveurs MCP locaux et distants.

Tous les serveurs MCP n’ont pas le même poids dans le workflow : certains constituent des piliers opérationnels quotidiens, tandis que d’autres interviennent de manière plus ponctuelle.

{
  "mcpServers": {
    "cloudflare-browser": {
      "url": "https://browser.mcp.cloudflare.com/mcp",
      "directTools": true
    },
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "directTools": true
    },
    "svelte": {
      "command": "bunx",
      "args": ["-y", "@sveltejs/mcp"]
    },
    "gitnexus": {
      "command": "bunx",
      "args": ["-y", "gitnexus", "mcp"]
    },
    "grep_app": {
      "url": "https://mcp.grep.app",
      "directTools": true
    },
    "cloudflare-api": {
      "url": "https://mcp.cloudflare.com/mcp",
      "directTools": true
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp",
      "auth": "oauth"
    },
    "posthog": {
      "url": "https://mcp.posthog.com/mcp"
    }
  }
}

1. `cloudflare-browser` : L’accès visuel et le scraping headless du Web moderne (Top Priorité)

C’est l’un des MCPs les plus cruciaux de la stack. Contrairement à un simple curl ou fetch textuel incapable d’exécuter du JavaScript, cloudflare-browser pilote une instance Chromium distante managée sur l’Edge de Cloudflare :

Rendu complet de SPAs & pages dynamiques : Conversion instantanée de pages web riches en Markdown propre (get_url_markdown) ou capture d’instantanés DOM (get_url_html_content).
Extraction intelligente structurée (get_url_json) : Extraction directe de schémas JSON typés à partir d’une page web via des invites de langage naturel.
Crawls asynchrones (start_crawl / get_crawl_result) : Exploration récursive de documentations ou de sites entiers en tâche de fond.

2. `context7` : La documentation officielle toujours à jour

Les connaissances natives des LLMs s’arrêtent à leur date de coupure d’entraînement (cutoff date) et souffrent d’hallucinations sur les versions majeures récentes de frameworks. context7 comble ce fossé :

Résolution précise de librairies (context7_resolve-library-id) : Identification exacte du package et de sa version.
Requêtage ciblé par concept (context7_query-docs) : Récupération d’extraits officiels concis, d’APIs actualisées et d’exemples de code officiels directement injectés dans le contexte.

3. `grep_app` : L’exploration de code réel sur GitHub

La documentation ne montre souvent que des exemples simplifiés (hello world). grep_app permet à l’agent d’inspecter l’usage d’une bibliothèque en conditions réelles de production :

Recherche de motifs de code littéraux et regex (grep_app_searchGitHub) parmi plus d’un million de dépôts GitHub publics.
Validation d’idiomes et de patterns : Vérification de signatures de fonctions, gestion d’erreurs réelles, configurations TypeScript avancées et intégrations entre bibliothèques tierces.

4. Les MCPs d’Infrastructure & Écosystème

cloudflare-api : Recherche dans la spécification OpenAPI et exécution directe d’appels API pour orchestrer Workers, D1, KV, R2, DNS et règles de sécurité.
github & posthog : Intégrations spécialisées pour l’accès aux APIs GitHub Copilot et l’analyse de métriques produit.

Le Runtime de Scripting `mcpScript`

Pour optimiser les performances et limiter les tokens consommés lors d’interactions complexes, pi-mcp-adapter fournit la fonction mcpScript. Elle permet à l’agent d’écrire et d’exécuter un snippet JavaScript trusted qui enchaîne plusieurs appels MCP (filtrage, boucles, requêtes parallèles) au sein d’une unique transaction, évitant de multiples allers-retours coûteux.

7. Boîte à Outils Spécialisée : Refactoring, Tâches & Contexte

En complément des extensions majeures, la stack intègre plusieurs modules spécialisés :

Module / Package	Rôle & Fonctionnalités Clés
`move-tool`	Déplacement de blocs de code entre fichiers avec calcul d’indentation, mode `dry_run` préalable et mécanisme de rollback automatique.
`pi-todotools`	Gestionnaire de tâches déterministe avec machines à états par phases (`Foundation`, `Implementation`, `Verification`).
Configuration locale	Séparation entre `settings.json` partageable et `preferences.json` local, afin de ne pas versionner les credentials, endpoints ou choix personnels.
`pi-apply-patch`	Application chirurgicale de diffs unifiés Git.

8. Système de Compétences Spécialisées (Skills)

Les Skills permettent de charger à la demande des ensembles de règles expertes et de directives méthodologiques selon le contexte du projet :

Architecture Cloudflare : cloudflare, wrangler, durable-objects, agents-sdk, sandbox-sdk, cloudflare-one.
Design Engineering & UI/UX : impeccable (audit ergonomique et typographique), make-interfaces-feel-better (micro-interactions, spring physics, polish d’interface), responsive-craft.
Règles de Qualité de Code : karpathy-guidelines (réduction des sur-complexifications LLM, modifications chirurgicales et validation par critères mesurables).
Performance & Debugging : web-perf (Core Web Vitals), web-debug (inspection Playwright live du DOM et réseau).

Workflow Quotidien & Bénéfices

En combinant l’ensemble de ces briques, le cycle de développement quotidien atteint un niveau d’efficacité inédit :

Initialisation de mission : Lancement d’une session Pi sur un dépôt de code. Les préférences locales sélectionnent le provider et les extensions, tandis que l’outil todo structure le plan d’action en phases ordonnées.
Exploration & Parallélisation : Pendant que l’agent principal élabore la logique métier, un sous-agent natif scout est détaché en arrière-plan avec une allowlist minimale pour chercher des exemples d’implémentation sur grep_app ou extraire la documentation via context7.
Sécurité & Contrôle Distant : Si une décision critique ou une commande shell sensible se présente alors que je suis en déplacement, une notification interactive arrive sur mon application Discord. Un simple clic valide le choix et l’agent poursuit son exécution.
Continuité Cognitive : Grâce à observational-memory, les enseignements tirés de chaque session (bugs résolus, préférences de framework, conventions d’API) persistent dans SQLite et enrichissent automatiquement les sessions futures. Les transcripts et les loadouts des sous-agents permettent également de reprendre un travail interrompu sans élargir ses permissions.

Conclusion

L’efficacité d’un agent de développement ne dépend pas uniquement de la puissance intrinsèque du modèle sous-jacent, mais de la richesse et de la robustesse de son environnement d’exécution.

En réunissant mémoire persistante déterministe, concurrence asynchrone, passerelle MCP connectée à un VPS Zero Trust, interactivité multi-canaux (TUI + Discord) et garde-fous de sécurité, cette stack transforme Pi en un véritable partenaire d’ingénierie logicielle autonome, fiable et taillé pour la production.