> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# pi (gateway)

> Set up pi with the Respan gateway.

Route [pi](https://pi.dev)'s LLM calls through the Respan gateway for automatic logging, caching, and model switching. pi loads custom providers from `~/.pi/agent/models.json`, so only your `RESPAN_API_KEY` is needed.

#### Trace pi sessions

This page covers gateway routing. To also capture turns, tool calls, and compactions from inside pi, see [pi (tracing)](/docs/integrations/pi).

## Setup

#### Install pi

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

#### Add Respan as a provider

Create or edit `~/.pi/agent/models.json`:

```json
{
  "providers": {
    "respan": {
      "baseUrl": "https://api.respan.ai/api",
      "api": "openai-completions",
      "apiKey": "$RESPAN_API_KEY",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "reasoning": false,
          "input": ["text", "image"],
          "cost": { "input": 2.5, "output": 10, "cacheRead": 1.25, "cacheWrite": 0 },
          "contextWindow": 128000,
          "maxTokens": 16384
        },
        {
          "id": "claude-sonnet-4-5-20250929",
          "name": "Claude Sonnet 4.5",
          "reasoning": true,
          "input": ["text", "image"],
          "cost": { "input": 3, "output": 15, "cacheRead": 0.3, "cacheWrite": 3.75 },
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}
```

Then export the key in your shell profile:

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

No separate provider key needed. The Respan gateway handles provider authentication.

#### Run pi

```bash
pi --model respan/gpt-4o
```

For a one-shot, non-interactive run:

```bash
pi -p --model respan/gpt-4o "your prompt"
```

All LLM calls now route through Respan.

## Switch models

Add more entries to the `models` array and pick any of them with `--model respan/<id>`. Any of the 1000+ models available through the gateway work, for example:

```text
gpt-4o
claude-sonnet-4-5-20250929
gemini/gemini-3.5-flash
```

See the [full model list](https://platform.respan.ai/platform/models).

## Use a provider-native API

pi also speaks the Anthropic Messages and OpenAI Responses protocols. Point those at the matching Respan passthrough if you prefer the native format:

```json
{
  "providers": {
    "respan-anthropic": {
      "baseUrl": "https://api.respan.ai/api/anthropic",
      "api": "anthropic-messages",
      "apiKey": "$RESPAN_API_KEY",
      "models": [{ "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5", "reasoning": true, "input": ["text", "image"], "cost": { "input": 1, "output": 5, "cacheRead": 0.1, "cacheWrite": 1.25 }, "contextWindow": 200000, "maxTokens": 64000 }]
    },
    "respan-responses": {
      "baseUrl": "https://api.respan.ai/api",
      "api": "openai-responses",
      "apiKey": "$RESPAN_API_KEY",
      "models": [{ "id": "gpt-5.5", "name": "GPT-5.5", "reasoning": true, "input": ["text", "image"], "cost": { "input": 2, "output": 8, "cacheRead": 0.2, "cacheWrite": 0 }, "contextWindow": 400000, "maxTokens": 128000 }]
    }
  }
}
```

The `openai-responses` route only serves OpenAI models. Use `openai-completions` for Claude, Gemini, and other providers.