Pi Agent Harness

Prérequis

Installation

Debian

# apt update && apt upgrade
# apt install npm

On créé un utilisateur Pi :

# adduser pi
# su - pi

On installe Pi avec l'installateur officiel :

# curl -fsSL https://pi.dev/install.sh | sh
# export PATH="/home/pi/.pi/agent/bin:$PATH"

On vérifie l'installation :

# pi --version

Configuration

Modèle local

# vi ~/.pi/agent/models.json

Par exemple, on crée un fournisseur local

{
  "providers": {
    "local": {
      "baseUrl": "https://192.168.1.123:8080/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "models": [
        {
          "id": "Qwen3.8-27B",
          "input": ["text", "image"]
        },
        {
          "id": "Muse-Glimmer",
          "input": ["text", "image"]
        }
      ]
    }
  }
}

On lance ensuite Pi :

# pi

Le fournisseur local peut être sélectionné avec :

/login local

Puis le modèle avec :

/model

Pendant la sélection du modèle avec /model, utiliser Ctrl+S sur le modèle choisi pour le définir comme modèle par défaut.

Abonnement ChatGPT

On lance Pi :

# pi

On utilise ensuite la commande /login :

/login

Puis on sélectionne :

→ Sign in with an account

→ OpenAI

Se rendre sur l'URL indiquée et suivre les instructions pour connecter son compte ChatGPT.

Une fois l'authentification terminée, de nouveaux modèles OpenAI seront disponibles via :

/model

Pendant la sélection du modèle avec /model, utiliser Ctrl+S sur le modèle choisi pour le définir comme modèle par défaut.

Choix du modèle pour la planification

Pour les tâches de planification, d'architecture logicielle ou de découpage d'un développement en plusieurs étapes, tous les modèles ne présentent pas le même rapport entre qualité de raisonnement et consommation du quota ChatGPT.

GPT-6.0 Astra: À privilégier pour les tâches de planification particulièrement complexes : architecture générale d'un projet, gros refactoring, choix techniques importants ou problèmes nécessitant un raisonnement en plusieurs étapes.; C'est le choix offrant la meilleure capacité de raisonnement, mais également l'un des plus coûteux en quota.

GPT-5.6 Sol: Recommandé comme modèle principal pour la planification.; Il offre un très bon niveau de raisonnement tout en consommant nettement moins de ressources que GPT-6.0 Astra.; Il convient particulièrement à la conception d'une fonctionnalité, à la création d'un plan d'implémentation ou à l'analyse d'une architecture existante.

GPT-5.6 Terra: À utiliser lorsqu'on souhaite réduire davantage la consommation du quota.; Il reste adapté aux tâches de planification courantes, mais sera moins fiable que GPT-5.6 Sol pour les problèmes d'architecture complexes.

GPT-5.6 Luna: Modèle rapide et économique, plutôt destiné aux tâches simples ou répétitives.; Il est moins recommandé comme modèle principal pour concevoir l'architecture d'une fonctionnalité importante.

Projets

# mkdir -p ~/projets/mon-projet
# cd ~/projets/mon-projet
# pi

Mise à jour

# pi update

Pi uniquement :

# pi update --self

Extensions/packages uniquement :

# pi update --extensions

Pi + extensions/packages :

# pi update --all

Extension

Package Catalog : Installation avec pi install npm:<package>

pi-web-access

Extension fournissant à Pi des outils natifs pour la recherche web et la consultation de pages, avec prise en charge locale de SearXNG et Firecrawl. # pi install npm:pi-web-access Pour utiliser SearXNG et Firecrawl, éditer :

# vi ~/.pi/agent/web-search.json

Ajouter :

{
  "searxngBaseUrl": "https://192.168.1.123:8080",
  "firecrawlBaseUrl": "https://192.168.1.123:3002",
  "searchRouting": {
    "providers": ["searxng", "firecrawl"],
    "useCurrentModel": false,
    "fallbackOn": ["transient", "quota", "network", "invalid-response"]
  },
  "fetchRouting": {
    "providers": ["firecrawl"],
    "allowRemoteHostedProviders": false
  },
  "fetch": {
    "timeout": 30,
    "defaultMode": "readable",
    "allowedModes": ["readable", "raw", "answer"],
    "answerProvider": "local",
    "answerModel": "Qwen3.8-27B"
  },
  "webSearch": {
    "enabled": true,
    "allowedProviders": ["searxng", "firecrawl"]
  },
  "tools": {
    "webSearch": { "enabled": true },
    "sourceCheck": { "enabled": true },
    "fetchContent": { "enabled": true },
    "getSearchContent": { "enabled": true }
  },
  "commands": {
    "websearch": { "enabled": true },
    "curator": { "enabled": true },
    "search": { "enabled": true },
    "google-account": { "enabled": true }
  },
  "ssrf": {
  "allowRanges": ["192.168.1.0/24"]
  }
}

pifox

Navigateur Camofox anti-détection intégré sous forme d’outils natifs pour l’agent, avec gestion à la demande de son cycle de vie.

# sudo apt-get update && sudo apt-get install -y libgtk-3-0t64 libdbus-glib-1-2 libasound2t64
# pi install npm:@munstar0s/pifox

billion-context

Un plugin de compression de contexte permettant d’utiliser de petites fenêtres de contexte, 100 000 tokens suffisent, de réduire jusqu’à cinq fois la consommation de tokens et de maintenir des sessions uniques pendant plusieurs mois, jusqu’à plusieurs milliards de tokens cumulés, tout en conservant une bonne qualité de compression. Compatible avec de nombreux agents, notamment Pi, OpenCode, Codex et Claude Code.

# pi install npm:billion-context

Par défaut, billion-context refuse d’enregistrer directement un serveur LLM accessible en HTTP sur une adresse IP locale autre que 127.0.0.1.

Pour utiliser un serveur LLM local accessible en HTTP sur une autre machine du réseau :

Installer également billion-context globalement :

# sudo npm install -g billion-context

Lancer ensuite Pi via bili :

# bili pi

bili démarre un proxy local et réécrit les providers concernés afin que Pi puisse utiliser le serveur LLM distant via 127.0.0.1.

pi-mnemosyne

Contrairement à son fonctionnement dans Hermes Agent, Mnemosyne n'est pas intégré automatiquement au cycle de mémoire de Pi Agent. Le modèle doit explicitement appeler les outils Mnemosyne pour effectuer les opérations de rappel ou de mémorisation. Pour une gestion automatique de la mémoire, préférer pi-memory.

[Développer]

Mémoire persistante locale pour Pi, avec stockage SQLite et outils natifs pour mémoriser, retrouver et supprimer des souvenirs.

# sudo apt update && apt upgrade
# sudo apt install python3-pip python3-full python3-venv
# python3 -m venv ~/.mnemosyne-venv

On installe Mnemosyne :

mnemosyne-memory → mémoire + recherche lexicale, très léger.
mnemosyne-memory[embeddings] → ajoute la recherche sémantique avec des embeddings locaux.
mnemosyne-memory[all] → installe toutes les fonctionnalités optionnelles, notamment les modèles locaux nécessaires aux fonctions avancées.

# ~/.mnemosyne-venv/bin/pip install mnemosyne-memory[embeddings]
# pi install npm:@mnemosyne-oss/pi-mnemosyne
# echo 'export PATH="$HOME/.mnemosyne-venv/bin:$PATH"' >> ~/.bashrc
# source ~/.bashrc

Configuration

# vi ~/.hermes/mnemosyne/config.yaml

Pour remplacer le LLM embedding par défaut qui est anglais uniquement par un modèle fournis :

...
embedding_dim: 384
embedding_model: BAAI/bge-small-en-v1.5
...

Modèle	Dimensions	Langue / Type
`BAAI/bge-small-en-v1.5`	384	English
`BAAI/bge-base-en-v1.5`	768	English
`BAAI/bge-small-zh-v1.5`	512	Chinese
`BAAI/bge-base-zh-v1.5`	768	Chinese
`BAAI/bge-large-zh-v1.5`	1,024	Chinese
`BAAI/bge-m3`	1,024	Multilingual
`intfloat/multilingual-e5-large`	1,024	Multilingual
`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	384	Multilingual
`sentence-transformers/all-MiniLM-L6-v2`	384	Multilingual
`sentence-transformers/paraphrase-multilingual-mpnet-base-v2`	768	Multilingual
`openai/text-embedding-3-small`	1,536	API
`openai/text-embedding-3-large`	3,072	API

Pour utiliser un embedding auto-hébergé :

...
embedding_api_key: 'MA_CLE'
embedding_api_url: 'http://MON_SERVEUR:8080/v1'
embedding_dim: 1024
embedding_model: 'TON_MODELE'
embeddings_off: false
embeddings_via_api: true
enhanced_recall: false
...

Pour utiliser un LLM auto-hébergé, exemple avec LFM2.5-2.6B :

...
llm_api_key: 'MA_CLE'
llm_base_url: 'http://MON_SERVEUR:8085/v1'
llm_conflict_detection: false
llm_enabled: true
llm_fallback_api_key: 
llm_fallback_base_url: 
llm_fallback_models: 
llm_file: 
llm_max_tokens: 2048
llm_model: 'LiquidAI_LFM2.5-2.6B'
llm_n_ctx: 131072
llm_n_threads: 4
llm_repo: 
llm_timeout: 60
...

pi-memory

Extension pour Pi Coding Agent ajoutant une mémoire avec recherche sémantique propulsée par QMD, couvrant les journaux quotidiens, la mémoire à long terme et le bloc-notes temporaire.

# pi install npm:pi-memory
# sudo npm install -g @tobilu/qmd

pi-mcp-adapter

Extension adaptatrice MCP (Model Context Protocol) pour Pi Coding Agent.

# pi install npm:pi-mcp-adapter

Puis pour configurer les instances MCP :

# mkdir -p  ~/.config/mcp
# vi ~/.config/mcp/mcp.json

RAGFlow

# vi ~/.config/mcp/mcp.json

{
  "mcpServers": {
    "ragflow": {
      "url": "http://192.168.1.123:9382/mcp",
      "headers": {
        "Authorization": "Bearer TON_API_KEY"
      }
    }
  }
}

pi-subagents

Extension Pi permettant la délégation à un agent unique et l’exécution de workflows multi-agents scriptés.

# pi install npm:pi-subagents

L’extension fournit plusieurs agents utilisables immédiatement :

Agent	Utilisation recommandée
`scout`	Exploration rapide du code local : fichiers pertinents, points d’entrée, flux de données et risques potentiels.
`researcher`	Recherche sur le Web et dans la documentation, avec sources et synthèse concise. Nécessite `pi-web-access` dans le sous-agent.
`evidence-auditor`	Vérifie de manière indépendante si les affirmations importantes issues d’une recherche sont réellement étayées par leurs sources. Nécessite également `pi-web-access`.
`worker`	Travaux d’implémentation : modification des fichiers, validation et tests. Remonte les décisions non prévues au lieu de les deviner.
`reviewer`	Relecture du code et petites corrections en fonction de la tâche ou du plan, des tests, des cas limites et de la simplicité de l’implémentation.
`oracle`	Second avis avant d’agir. Remet en question les hypothèses et les choix techniques sans modifier les fichiers.
`delegate`	Agent généraliste léger, au comportement proche de celui de la session principale.

Règle pratique :

utiliser scout avant de bien connaître le code ;
utiliser researcher avant de se fier à des informations externes ;
utiliser evidence-auditor avant de s’appuyer sur des résultats de recherche importants ;
utiliser worker pour l’implémentation ;
utiliser reviewer pour vérifier le travail effectué ;
utiliser oracle lorsqu’une décision semble risquée ou mérite un second avis.

Exemple de configuration de délégation

Les agents intégrés utilisent par défaut le même modèle que la session Pi principale. Il est possible d'affecter un modèle différent à chaque rôle dans le fichier :

~/.pi/agent/settings.json

Exemple avec :

Qwen3.8-27B comme modèle local pour l'analyse, l'exploration du projet et l'implémentation ;
LiquidAI_LFM2.5-2.6B comme petit modèle rapide pour la recherche et les tâches légères ;
inherit pour utiliser le modèle actuellement sélectionné dans la session Pi principale, par exemple GPT-5.6 Sol.

# vi ~/.pi/agent/settings.json

{
  "subagents": {
    "agentOverrides": {
      "scout": {
        "model": "local/Qwen3.8-27B"
      },
      "researcher": {
        "model": "local/Qwen3.8-27B"
      },
      "evidence-auditor": {
        "model": "local/Qwen3.8-27B"
      },
      "worker": {
        "model": "local/Qwen3.8-27B"
      },
      "reviewer": {
        "model": "inherit"
      },
      "oracle": {
        "model": "inherit"
      },
      "delegate": {
        "model": "auxgeneralist/LiquidAI_LFM2.5-2.6B"
      }
    }
  }
}

Dans cet exemple :

Agent	Modèle	Rôle
`scout`	Qwen3.8-27B	Exploration et compréhension du projet.
`researcher`	LiquidAI_LFM2.5-2.6B	Recherche Web et consultation de documentation à faible coût.
`evidence-auditor`	Qwen3.8-27B	Vérification des résultats de recherche et de la validité des sources.
`worker`	Qwen3.8-27B	Implémentation, modification des fichiers et exécution des tests.
`reviewer`	`inherit`	Utilise le modèle de la session principale pour effectuer la revue du travail.
`oracle`	`inherit`	Utilise le modèle de la session principale pour les décisions importantes et les seconds avis.
`delegate`	LiquidAI_LFM2.5-2.6B	Petites tâches générales, simples et rapides.

inherit indique que le sous-agent doit utiliser le modèle actuellement sélectionné dans la session Pi parente. Si la session principale utilise GPT-5.6 Sol, les agents reviewer et oracle utiliseront donc également GPT-5.6 Sol.

Il faut ensuite configurer les instructions système afin d'autoriser et d'encourager la délégation automatique des tâches.

Le fichier AGENTS.md n'est pas créé par défaut et doit être créé manuellement si nécessaire.

Pour une configuration globale :

# vi ~/.pi/agent/AGENTS.md

Pour des instructions propres à un projet (recommandé) :

# vi ~/chemin/projet/AGENTS.md

Puis on ajoute :

For any non-trivial implementation task, implementation must be delegated to subagents.

- The parent agent is responsible for planning, orchestration, architectural decisions, and final validation.
- The parent agent must not directly edit project files or implement substantial code unless explicitly requested by the user.
- Use `scout` when the relevant code, files, or architecture are not yet clearly identified.
- Create the implementation plan in the parent session.
- Delegate all substantial implementation work to `worker`.
- If implementation changes or fixes are required after review, delegate them back to `worker` instead of applying them in the parent session.
- Use `reviewer` after implementation to validate the result.
- The reviewer should report issues rather than implement substantial fixes itself.
- Use `oracle` before making important, risky, or difficult architectural decisions.
- For external research, use `researcher`, then `evidence-auditor` when independent verification is useful.
- Small and trivial changes may be handled directly by the parent agent.