Pi

Connect the Pi terminal coding agent to CoffeeRouter with a custom provider in models.json.

Before You Begin

  • Install a Node.js version supported by the current Pi release.
  • Create a dedicated CoffeeRouter API key and note the target model ID.
  • Use https://www.coffeerouter.ai/v1 as the OpenAI-compatible Base URL.

Configuration Steps

1. Install Pi

Install the current official npm package:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

You can also use the official installer:

curl -fsSL https://pi.dev/install.sh | sh

2. Set the API Key

Linux / macOS:

export COFFEEROUTER_API_KEY="sk-your-api-key"

Windows PowerShell:

$env:COFFEEROUTER_API_KEY="sk-your-api-key"

3. Create the Model Configuration

Add CoffeeRouter to ~/.pi/agent/models.json:

{
    "providers": {
        "coffeerouter": {
            "baseUrl": "https://www.coffeerouter.ai/v1",
            "api": "openai-completions",
            "apiKey": "$COFFEEROUTER_API_KEY",
            "models": [
                {
                    "id": "your-model-id",
                    "name": "CoffeeRouter Model",
                    "reasoning": false,
                    "input": ["text"],
                    "contextWindow": 128000,
                    "maxTokens": 8192
                }
            ]
        }
    }
}

Match all capability fields to the actual CoffeeRouter model. Do not apply one set of reasoning compatibility options to every model.

4. Select the Model

Start Pi, enter /model or press Ctrl+L, then select coffeerouter and the target model. Pi reloads models.json when the model selector opens.

Verify the Integration

After selecting the model, send a small coding task. Normal streaming output and basic tool execution confirm the configuration.

Reasoning Models

Use the Current thinkingLevelMap

Current Pi releases replaced the old compat.reasoningEffortMap with a model-level thinkingLevelMap. Add it only after confirming that the target model accepts the mapped reasoning levels. For example:

{
    "id": "your-reasoning-model-id",
    "reasoning": true,
    "thinkingLevelMap": {
        "minimal": "low",
        "low": "low",
        "medium": "medium",
        "high": "high",
        "xhigh": null
    }
}

Do not copy the obsolete thinkingFormat: "anthropic" example. It is not among the OpenAI compatibility formats in the current Pi documentation.

FAQ

Why is the provider or model missing?

Confirm that the file is ~/.pi/agent/models.json, the JSON is valid, and COFFEEROUTER_API_KEY is set. Without usable authentication, a model can load but remain unavailable in the selector.

Why does Pi return 401?

Set the API key again and launch Pi from the same shell. Check whether the CoffeeRouter token is expired, disabled, or restricted.

Why does a reasoning model behave incorrectly?

Remove custom compat and thinkingLevelMap settings first and verify a normal request. Then add compatibility options one at a time according to the specific model protocol.

Can I keep using an old Pi configuration?

The old repository name, old npm package, and reasoningEffortMap are outdated. New configuration should use earendil-works/pi, @earendil-works/pi-coding-agent, and model-level thinkingLevelMap.

Security

  • Never put a real key in documentation, screenshots, session logs, or version control.
  • Pi extensions and skills can execute code. Review the source and permissions before installing third-party packages.
  • Use a dedicated CoffeeRouter token for Pi and restrict models and quota as needed.
  • Pi sends prompts, necessary code context, and tool-call data to CoffeeRouter.

Official Resources