Pi

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.

Config file path

Pi docs use home-relative paths for global config and project-local .pi paths for overrides:

Path	Scope
~/.pi/agent/models.json	Global custom providers and models
~/.pi/agent/settings.json	Global defaults, UI behavior, resource paths, and project trust fallback
~/.pi/agent/trust.json	Saved project trust decisions
~/.pi/agent/sessions/	Saved sessions
.pi/settings.json	Project settings that override and merge with global settings

On Windows, use the same home-relative paths under the user profile, for example %USERPROFILE%\.pi\agent\models.json and %USERPROFILE%\.pi\agent\settings.json.

Install

Use the current npm package:

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:

{
  "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,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 272000,
          "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.

thinkingLevelMap.xhigh is required for Pi to expose xhigh for this custom model. Without it, Pi clamps --thinking xhigh and defaultThinkingLevel: "xhigh" down to high.

Pi accepts contextWindow and maxTokens for custom models; it has no contextTokens field. The bundled Pi gpt-5.5 entries use a 272k context window and 128k output budget, so matching those values keeps Codex Pooler custom-provider behavior aligned with Pi’s built-in metadata.

Default model

If you want plain pi or pi -p ... to start on Codex Pooler, add the defaults to ~/.pi/agent/settings.json:

{
  "defaultProvider": "codex-pooler",
  "defaultModel": "gpt-5.5",
  "defaultThinkingLevel": "xhigh",
  "enabledModels": ["codex-pooler/gpt-5.5"],
  "compaction": {
    "reserveTokens": 128000
  }
}

Connection Check

Run a one-shot prompt from the repository you want Pi to inspect:

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 it 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.