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

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

Or use pnpm or bun:

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 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:

{
  "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):

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:

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:

{
  "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.

Troubleshooting