# 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:

```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,
          "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`:

```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:

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