---
title: Pi Coding Agent
---


[Pi](https://github.com/earendil-works/pi) is an open-source terminal AI coding agent built around four core tools (read, write, edit, bash). It connects to any OpenAI-compatible provider through `models.json`.

## Quickstart

### 1. Install Pi

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

Or use pnpm or bun:

```bash
pnpm add -g @earendil-works/pi-coding-agent
# or
bun add -g @earendil-works/pi-coding-agent
```

### 2. Create an API key

Sign in to the [Console](/console/api-keys) and create a key that starts with `cm-` on the **API Keys** page. The key is shown only once, so copy it somewhere safe.

### 3. Point Pi at CrossModel

Edit `~/.pi/agent/models.json` (create it if it doesn't exist) and add the CrossModel provider:

```json
{
  "providers": {
    "crossmodel": {
      "baseUrl": "https://api.crossmodel.ai/v1",
      "api": "openai-completions",
      "apiKey": "$CROSSMODEL_API_KEY",
      "models": [
        {
          "id": "deepseek/deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 16384,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}
```

`models.json` hot-reloads — run `/model` during a session to see the latest config without restarting.

### 4. Set the API key environment variable

`"apiKey": "$CROSSMODEL_API_KEY"` reads the key from the matching environment variable. Add it to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash
export CROSSMODEL_API_KEY="cm-YOUR_KEY"
```

Reopen the terminal, or run `source ~/.zshrc`, to load it.

### 5. Launch

Run Pi from your project directory:

```bash
cd /path/to/your/project
pi
```

Type `/model` in a session to switch models.

## Adding more models

Append more entries to the `providers.crossmodel.models` array, following this shape:

```json
{
  "id": "openai/gpt-5-mini",
  "name": "GPT-5 Mini",
  "reasoning": false,
  "input": ["text"],
  "contextWindow": 128000,
  "maxTokens": 16384,
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
}
```

Model IDs follow the `vendor/short_name` format; see the full list in the [model catalog](/models).

## Troubleshooting

| Symptom | What to check |
|---------|---------------|
| Auth failure | Confirm `CROSSMODEL_API_KEY` is set, active in the current shell, and holds a valid `cm-` key. |
| CrossModel missing from `/model` | Make sure `models.json` is valid JSON and the `providers.crossmodel` block is complete. |
| "Model not found" | Verify the `id` values in `models` match IDs from the `/v1/models` response. |
| Insufficient balance | Top up in the [Console](/console/billing). |