> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openference.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi

> Configure the Pi coding agent (pi.dev) with Openference.

# Pi

Pi is a minimal, extensible coding agent harness. Use the official Openference package for sign-in, model discovery, and Pi-tuned context limits.

## Install the provider

```bash theme={null}
pi install npm:@openference/pi-provider
```

Restart Pi, then run:

```text theme={null}
/login openference
```

Choose **Browser link**. Pi prints a URL — click it or copy it into a browser, sign in to Openference if needed, and approve. After approval, Pi refreshes your model catalog automatically (via `refreshModels`).

Select a model:

```text theme={null}
/model openference/GLM-5.2
```

Tokens are stored in `~/.pi/agent/auth.json`. You can also paste an API key during `/login`, or set `OPENFERENCE_API_KEY` in your shell.

If you change model restrictions in the dashboard, run `/reload` in Pi to refresh the catalog.

## What the package configures

* Live model list from `GET /v1/models` (only models your account can use)
* Safe context windows and max output tokens so Pi compacts at the right time
* Reasoning / thinking levels from each model’s supported efforts
* Request pacing from your plan’s RPM limit, and correct `Retry-After` handling on rate limits

If you keep hitting plan limits, [upgrade or add credits](https://openference.com/dashboard).

## Manual models.json (advanced)

If you prefer not to use the package, create or edit `~/.pi/agent/models.json`:

```json theme={null}
{
  "providers": {
    "openference": {
      "baseUrl": "https://api.openference.com/v1",
      "apiKey": "$OPENFERENCE_API_KEY",
      "api": "openai-completions",
      "headers": {
        "User-Agent": "pi/openference"
      },
      "models": [
        {
          "id": "GLM-5.2",
          "name": "GLM-5.2 (via Openference)",
          "contextWindow": 850000,
          "maxTokens": 128000
        }
      ]
    }
  }
}
```

> **Important:** set `contextWindow` and `maxTokens` on every model entry. Pi
> falls back to a 128000-token context window and a 16384-token output cap when
> these are omitted, which is far below what larger models support — Pi will
> start compacting the session well before the real limit. See
> [Context window values](#context-window-values) below.

Export your API key in the shell (add to your profile for persistence):

```bash theme={null}
export OPENFERENCE_API_KEY="YOUR_API_KEY"
```

## The User-Agent header is required

Pi only sends a `pi/` User-Agent on version checks — not on custom OpenAI-compatible API calls. Without the `headers` block above (or the official package, which sets it for you), requests arrive with a generic or missing User-Agent and are rejected with a 403 "coding agent required" error.

## Context window values

Use these values in each model entry's `contextWindow` and `maxTokens` fields when configuring `models.json` by hand.
The `contextWindow` is the safe **input** budget — the model's total context
wall minus `maxTokens`, with a small \~2% safety buffer. Models with a smaller
output cap get a larger input budget.

| Model             | `contextWindow` | `maxTokens` |
| ----------------- | --------------- | ----------- |
| GLM-5.2           | 850000          | 128000      |
| DeepSeek-V4-Pro   | 850000          | 131072      |
| DeepSeek-V4-Flash | 850000          | 131072      |
| Qwen3 Code        | 915000          | 65536       |
| Qwen3.7 Plus      | 915000          | 65536       |

`GET /v1/models` also advertises each model's `context_length` and
`max_output_tokens`, so you can always look up the current values:

```bash theme={null}
curl https://api.openference.com/v1/models \
  -H "Authorization: Bearer $OPENFERENCE_API_KEY"
```

## Troubleshooting

* **403 coding agent required** — the User-Agent header is missing. Use the official package, or add the `headers` block shown above.
* **Session compacts too early** — `contextWindow` is missing or set too low on the model entry. Prefer the official package (it sets this automatically), or add values from the [Context window values](#context-window-values) table.
* **404 model not configured** — check the model ID against `GET /v1/models`.
* **Login link expired** — run `/login openference` again and open the new link.

See the [Compatibility Matrix](/integrations/compatibility-matrix) for an overview of all clients.