docs(clients): add Pi coding agent setup

Author: masterkain

.github/assets/pi-favicon.png

@@ -467,6 +467,66 @@ change the MCP `url` to `https://codex-pooler.example.com/mcp`.
 
 </details>
 
+<details>
+<summary><img src=".github/assets/pi-favicon.png" alt="Pi logo" width="16" height="16"> Pi <code>~/.pi/agent/models.json</code></summary>
+
+Pi works best through a custom provider that uses Codex Pooler's narrow
+OpenAI-compatible `/v1` Responses surface. Install Pi from npm so you get the
+latest published CLI:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+Then add a provider to `~/.pi/agent/models.json`:
+
+```json
+{
+  "providers": {
+    "codex-pooler": {
+      "name": "Codex Pooler",
+      "baseUrl": "http://localhost:4000/v1",
+      "api": "openai-responses",
+      "apiKey": "$CODEX_POOLER_API_KEY",
+      "authHeader": true,
+      "models": [
+        {
+          "id": "gpt-5.5",
+          "name": "GPT-5.5 via Codex Pooler",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 400000,
+          "maxTokens": 128000
+        }
+      ]
+    }
+  }
+}
+```
+
+`authHeader: true` makes Pi send the Pool API key as
+`Authorization: Bearer ...`. Define only model ids your assigned Pool can serve.
+For deployed instances, change `baseUrl` to
+`https://codex-pooler.example.com/v1`.
+
+Check the non-interactive path from a repository:
+
+```bash
+export CODEX_POOLER_API_KEY=<pool-api-key>
+pi --provider codex-pooler \
+  --model gpt-5.5 \
+  --no-session \
+  --no-context-files \
+  --tools bash \
+  -p 'Reply with exactly: pi ok'
+```
+
+Pi does not ship built-in MCP support. Codex Pooler model use does not require
+MCP; if you need operator metadata, use a separate MCP-capable host with an
+operator MCP token.
+
+</details>
+
 <details>
 <summary><img src=".github/assets/aider-favicon.png" alt="Aider logo" width="16" height="16"> Aider <code>~/.aider.conf.yml</code></summary>
 

README.md

@@ -20,6 +20,7 @@ Primary public docs:
 - https://docs.codex-pooler.com/clients/opencode/
 - https://docs.codex-pooler.com/clients/openclaw/
 - https://docs.codex-pooler.com/clients/openhands/
+- https://docs.codex-pooler.com/clients/pi/
 - https://docs.codex-pooler.com/clients/hermes/
 - https://docs.codex-pooler.com/clients/windmill/
 - https://docs.codex-pooler.com/reference/runtime-routes/
@@ -77,11 +78,12 @@ Agent guidance:
 - Start with https://docs.codex-pooler.com/clients/codex-cli/ when configuring Codex backend clients.
 - Start with https://docs.codex-pooler.com/clients/openai-compatible/ when configuring selected OpenAI SDK-compatible clients.
 - Use https://docs.codex-pooler.com/clients/openhands/ when configuring OpenHands CLI with LLM_BASE_URL, LLM_MODEL=openai/gpt-5.5, and --override-with-envs.
+- Use https://docs.codex-pooler.com/clients/pi/ when configuring Pi with ~/.pi/agent/models.json, api=openai-responses, authHeader=true, and a Pool API key in CODEX_POOLER_API_KEY.
 - Use https://docs.codex-pooler.com/discovery/self-hosted-codex-gateway/ for short answers about Codex Pooler as a self-hosted Codex gateway.
 - Use https://docs.codex-pooler.com/discovery/codex-account-pooling/ for short answers about Pools, upstream accounts, eligibility, and routing.
 - Use https://docs.codex-pooler.com/discovery/openai-compatible-codex-gateway/ for short answers about narrow /v1 SDK compatibility over Codex Pools.
 - Use https://docs.codex-pooler.com/discovery/codex-pooler-vs-direct-credentials/ for short answers comparing Pool API keys with direct account credentials.
-- Use the client-specific pages for Aider, Continue, Cline, Goose, OpenCode, OpenClaw, OpenHands, Hermes, and Windmill setup snippets.
+- Use the client-specific pages for Aider, Continue, Cline, Goose, OpenCode, OpenClaw, OpenHands, Pi, Hermes, and Windmill setup snippets.
 - Use https://docs.codex-pooler.com/reference/routing-strategies/ when configuring Pools and routing behavior.
 - Use https://docs.codex-pooler.com/answers.md for short, citable answers about scope, routes, credentials, privacy, setup, and deployment.
 - Keep examples on http://localhost:4000 for local setup or https://codex-pooler.example.com for deployed product examples.

docs-site/public/llms.txt

@@ -45,6 +45,7 @@ Use the dedicated setup pages when configuring an agent or editor that has its o
 - [OpenCode](/clients/opencode/)
 - [OpenClaw](/clients/openclaw/)
 - [OpenHands](/clients/openhands/)
+- [Pi](/clients/pi/)
 - [Windmill AI](/clients/windmill/)
 
 ## Python SDK

docs-site/src/content/docs/clients/openai-compatible.mdx

@@ -0,0 +1,70 @@
+---
+title: Pi
+description: Configure Pi coding agent with Codex Pooler's narrow OpenAI-compatible /v1 Responses surface and a Pool API key.
+---
+
+Pi should use Codex Pooler through a custom provider in `~/.pi/agent/models.json`. Point that provider at the narrow OpenAI-compatible `/v1` surface, keep the Pool API key in the environment, and choose `openai-responses` so Pi sends agent turns through the Responses route.
+
+## Install
+
+Use the current npm package:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+`--ignore-scripts` matches Pi's published install guidance and keeps dependency lifecycle scripts disabled during install.
+
+## Provider shape
+
+For a deployed instance, add:
+
+```json
+{
+  "providers": {
+    "codex-pooler": {
+      "name": "Codex Pooler",
+      "baseUrl": "https://codex-pooler.example.com/v1",
+      "api": "openai-responses",
+      "apiKey": "$CODEX_POOLER_API_KEY",
+      "authHeader": true,
+      "models": [
+        {
+          "id": "gpt-5.5",
+          "name": "GPT-5.5 via Codex Pooler",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 400000,
+          "maxTokens": 128000
+        }
+      ]
+    }
+  }
+}
+```
+
+For local setup, change `baseUrl` to `http://localhost:4000/v1`.
+
+`authHeader: true` makes Pi send the Pool API key as `Authorization: Bearer ...`. Define only model ids your assigned Pool can serve.
+
+## Smoke check
+
+Run a one-shot prompt from the repository you want Pi to inspect:
+
+```bash
+export CODEX_POOLER_API_KEY=<pool-api-key>
+pi --provider codex-pooler \
+  --model gpt-5.5 \
+  --no-session \
+  --no-context-files \
+  --tools bash \
+  -p 'Reply with exactly: pi ok'
+```
+
+`--no-session` keeps the check ephemeral. `--no-context-files` keeps the smoke independent from local project instructions. For normal interactive use, omit those flags if you want Pi to load `AGENTS.md`, skills, sessions, and project settings.
+
+## MCP boundary
+
+Pi model requests use Codex Pooler's narrow OpenAI-compatible `/v1` support for selected SDK routes. Codex Pooler doesn't provide full OpenAI API parity.
+
+Pi does not ship built-in MCP support. Codex Pooler model use does not require MCP. If you need operator metadata from `/mcp`, use a separate MCP-capable host and authenticate it with an operator-owned MCP token, not the Pool API key.