> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# pi

> Run the pi terminal coding agent on Opper, with native provider support and session tracing

[pi](https://pi.dev) is a terminal-based coding agent. It has the deepest Opper integration of any agent here: a first-party provider package that adds the full catalog, automatic session span tracing, and seven multimodal tools.

## Setup

<Tip>
  One command, no config files:

  ```bash theme={null}
  npx @opperai/cli launch pi
  ```

  This adds an `opper` provider entry to `~/.pi/agent/models.json` — idempotently, alongside any existing providers — and starts pi.
</Tip>

### Native provider package

For the full integration, install `@opperai/pi-provider`:

```bash theme={null}
pi install npm:@opperai/pi-provider
export OPPER_API_KEY=your-opper-api-key
```

This gives you three things the plain provider block doesn't:

* **The whole catalog** in the `/model` picker, not a hand-listed subset.
* **Automatic session span tracing** — every turn in a pi session lands under one trace in Opper.
* **Seven multimodal tools** registered directly in pi: image generation, image analysis, text-to-speech, speech-to-text, web search, web fetch, and embeddings.

### Load only the provider or only the tools

Both halves load by default. To take one, name the extensions explicitly in `~/.pi/agent/config.json`:

```json theme={null}
{
  "packages": [
    {
      "source": "npm:@opperai/pi-provider",
      "extensions": ["extensions/provider.ts", "extensions/tools.ts"]
    }
  ]
}
```

Drop either entry from `extensions` to load just the other half.

## Choosing a model

Use `/model` inside a session. With the provider package installed, the picker lists the full [catalog](/capabilities/models).

## Environment variables

| Variable             | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `OPPER_API_KEY`      | Your Opper API key                                               |
| `OPPER_AGENT_NAME`   | Override the framework name sent in headers (default: `pi-code`) |
| `PI_IMAGE_SAVE_MODE` | Default image save mode: `tmp`, `project`, `global`, or `custom` |

## Related

<CardGroup cols={2}>
  <Card title="Traces" icon="chart-line" href="/control-plane/trace">
    Session spans from pi, grouped per conversation.
  </Card>

  <Card title="All integrations" icon="plug" href="/integrations/overview">
    Every app that runs on Opper.
  </Card>
</CardGroup>