Skip to main content

​
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

Restart Pi, then run:
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:
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.

​
Manual models.json (advanced)

If you prefer not to use the package, create or edit ~/.pi/agent/models.json:
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 below.
Export your API key in the shell (add to your profile for persistence):

​
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. Under dynamic context stacking, contextWindow is the total context window (context_length), shared between prompt and output. GET /v1/models also advertises each model’s context_length and max_output_tokens, so you can always look up the current values:

​
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 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 for an overview of all clients.