Pi Agent Harness

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.

Ajuster la fenêtre maximale de contexte des réponses

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

Ajouter :

...
        {
          "id": "Qwen3.8-Flash-Next",
          "input": ["text", "image"],
          "maxTokens": 32768
        },

La valeur par défaut est 16384

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"
      }
    }
  }
}

Blender

module mcp-server Voir site pour installer le plugin sur le client.

Si Blender ne tourne pas sur l'hôte de Pi agent il faut autoriser l'accès réseau : Edition -> Préférences... -> Add-ons -> MCP. Dans les préférences du serveur MCP, pour le champ Host: remplacer localhost par l'IP de l'hôte de Blender et redémarrer le serveur MCP plus bas.

Serveur MCP sur l'hôte de Pi Agent :

# curl -LsSf https://astral.sh/uv/install.sh | sh

source "$HOME/.local/bin/env"

# uv tool install --python 3.11 \
 "git+https://projects.blender.org/lab/blender_mcp.git#subdirectory=mcp"

Ou :

 # uv tool install --python 3.11 \
  "git+https://projects.blender.org/lab/blender_mcp.git@v1.0.3#subdirectory=mcp"

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

...
    "blender": {
      "command": "/home/NOM_UTILISATEUR/.local/bin/blender-mcp",
      "env": {
        "BLENDER_MCP_HOST": "IP_BLENDER",
        "BLENDER_MCP_PORT": "9876"
      }
    }
  }
}

Unreal Engine

Dans Modifier -> Plug-ins -> Activer Unreal MCP et All Toolsets puis redémarrer Unreal Engine. Puis dans Modifier → Préférences de l’éditeur → Général → Model Context Protocol → activer Démarrage automatique du serveur

Par défault le MCP Unreal n'écoute que sur la machine ou il s'éxécute, pour autoriser l'écoute sur une IP :

• Windows :

Ouvrir ..\mon_projet\Config\DefaultEngine.ini et ajouter à la fin :

[HTTPServer.Listeners]
DefaultBindAddress=0.0.0.0

Puis redémarrer Unreal Engine.

Pour configurer le plugin de Pi Agent :

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

...
    "unreal": {
      "type": "http",
      "url": "http://IP_PC_UNREAL:8000/mcp"
    }
  }
}

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, la recherche, la délégation et l'implémentation ;
• 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": "local/Qwen3.8-27B"
      }
    }
  }
}

Dans cet exemple :

Agent	Modèle	Rôle
scout	Qwen3.8-27B	Exploration et compréhension du projet.
researcher	Qwen3.8-27B	Recherche Web, consultation de documentation et synthèse des informations recueillies.
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	Qwen3.8-27B	Tâches générales déléguées ne correspondant pas à un rôle plus spécialisé.

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.
- Use `delegate` for general delegated tasks that do not clearly belong to another specialized role.
- Small and trivial changes may be handled directly by the parent agent.