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

# pi

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[pi](https://pi.dev) is a minimal terminal coding harness. The [`@braintrust/pi-extension`](https://github.com/braintrustdata/braintrust-pi-extension) package automatically traces pi sessions to Braintrust, including turns, model calls, and tool executions.

<Note>
  This page documents interactive pi sessions with the Braintrust pi extension. To trace `@earendil-works/pi-coding-agent` SDK usage in your own application, see [Pi Coding Agent SDK](/integrations/agent-frameworks/pi-coding-agent).
</Note>

## Prerequisites

<Steps>
  <Step title="Install pi">
    If you haven't already, install [pi](https://github.com/mariozechner/pi-coding-agent):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    npm install -g @mariozechner/pi-coding-agent
    ```
  </Step>

  <Step title="Install the Braintrust extension">
    Install the package with pi:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    pi install npm:@braintrust/pi-extension
    ```

    <Tip>
      Use the `-l` flag if you want a project-local install instead of a global one.
    </Tip>

    For a one-off run without installing it permanently, load the extension directly:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    pi -e npm:@braintrust/pi-extension
    ```

    <Note>
      This release supports pi v0.65.0 or later. On pi versions before 0.65.0, session switch and fork events are no longer traced.
    </Note>
  </Step>

  <Step title="Set your Braintrust environment variables">
    Tracing is disabled by default. Enable it and provide your API key:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    export TRACE_TO_BRAINTRUST=true
    export BRAINTRUST_API_KEY="YOUR_API_KEY"
    export BRAINTRUST_PROJECT="pi"
    ```

    Restart pi after changing environment variables.
  </Step>
</Steps>

## Usage

Once enabled, the extension traces each pi session as a hierarchy of spans:

* **Session spans**: One root span per pi session that produces at least one turn, with metadata capturing the session ID and name, hostname, username, operating system, working directory, repository, pi version, and extension version. At session close, the span records the total turn and tool-call counts and the close reason.
* **Turn spans**: One span per user prompt or agent run. When pi fires an input event, turn spans also capture `input_source`, `input_streaming_behavior`, `input_image_count`, and `raw_input` (a truncated copy of the prompt text).
* **LLM spans**: One span per model response inside a turn.
* **Tool spans**: One span per tool execution.
* **Compaction spans**: One span per context-window compaction, capturing the compaction reason, whether pi will retry, and the token counts before and after.
* **Branch Summary spans**: One span each time pi summarizes a branch while navigating the session's history tree, capturing the entries being condensed and the resulting summary.

Example trace structure:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
Session (task)
├── Turn 1 (task)
│   ├── anthropic/claude-sonnet-4 (llm)
│   │   ├── read: package.json (tool)
│   │   └── bash: pnpm test (tool)
│   └── anthropic/claude-sonnet-4 (llm)
├── Compaction (task)
├── Branch Summary (task)
└── Turn 2 (task)
```

In interactive mode, pi shows:

* A `Braintrust` status indicator in the footer while tracing is active
* A trace widget below the editor with a shortened clickable Braintrust trace link when available

To view traces, go to [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) in your Braintrust project.

## Configuration

You can configure the extension with environment variables or JSON config files.

Configuration precedence is:

1. Defaults
2. `~/.pi/agent/braintrust.json`
3. `<pi-config-dir>/braintrust.json`
4. Environment variables

### Config file locations

* Global: `~/.pi/agent/braintrust.json`
* Project: `<pi-config-dir>/braintrust.json`, where `<pi-config-dir>` follows pi's configured project directory and defaults to `.pi`.

<Note>
  The project config directory follows pi's `CONFIG_DIR_NAME` setting, so a custom directory such as `.custom-pi` is used automatically. Older pi versions that don't expose this setting always use `.pi`. The global config path (`~/.pi/agent/braintrust.json`) is not affected.
</Note>

Example:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "trace_to_braintrust": true,
  "project": "pi",
  "debug": true,
  "additional_metadata": {
    "team": "platform"
  }
}
```

### Supported settings

| Config key            | Env var                          | Default                                     | Description                                                                                                                                                      |
| --------------------- | -------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trace_to_braintrust` | `TRACE_TO_BRAINTRUST`            | `false`                                     | Enable or disable tracing                                                                                                                                        |
| `api_key`             | `BRAINTRUST_API_KEY`             | unset                                       | Braintrust API key                                                                                                                                               |
| `api_url`             | `BRAINTRUST_API_URL`             | `https://api.braintrust.dev`                | Braintrust API base URL. For EU organizations, use `https://api-eu.braintrust.dev`. For [self-hosted](/admin/self-hosting) deployments, use your data plane URL. |
| `app_url`             | `BRAINTRUST_APP_URL`             | `https://www.braintrust.dev`                | Braintrust app URL                                                                                                                                               |
| `org_name`            | `BRAINTRUST_ORG_NAME`            | unset                                       | Organization name for project-scoped links                                                                                                                       |
| `project`             | `BRAINTRUST_PROJECT`             | `pi`                                        | Braintrust project that receives traces                                                                                                                          |
| `debug`               | `BRAINTRUST_DEBUG`               | `false`                                     | Enable debug logging                                                                                                                                             |
| `additional_metadata` | `BRAINTRUST_ADDITIONAL_METADATA` | `{}`                                        | Extra metadata attached to session spans. When set via environment variable, pass a JSON object string.                                                          |
| `log_file`            | `BRAINTRUST_LOG_FILE`            | unset                                       | Write extension logs to a file. Set to `true` or `auto` to use the default log path.                                                                             |
| `state_dir`           | `BRAINTRUST_STATE_DIR`           | `~/.pi/agent/state/braintrust-pi-extension` | Directory for extension session state and default logs                                                                                                           |
| `parent_span_id`      | `PI_PARENT_SPAN_ID`              | unset                                       | Parent span ID for attaching pi traces under an existing trace                                                                                                   |
| `root_span_id`        | `PI_ROOT_SPAN_ID`                | unset                                       | Root span ID to use when attaching to an existing trace                                                                                                          |

## Embed traces in parent traces

You can attach a pi session under an existing Braintrust trace. This is useful when pi is part of a larger workflow and you want the entire interaction to appear inside a parent trace.

To attach a pi session under an existing span, set `PI_PARENT_SPAN_ID`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export PI_PARENT_SPAN_ID="your-parent-span-id"
pi
```

When the parent span is not the trace root, also set `PI_ROOT_SPAN_ID`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export PI_PARENT_SPAN_ID="parent-span-id"
export PI_ROOT_SPAN_ID="root-span-id"
pi
```

## Troubleshooting

<Accordion title="No traces are appearing">
  * Verify `TRACE_TO_BRAINTRUST=true`.
  * Verify `BRAINTRUST_API_KEY` is set in the shell where you launch pi.
  * Restart pi after changing environment variables or config files.
  * Run at least one prompt. A session root span is only created for sessions that actually produce a turn.
</Accordion>

<Accordion title="pi shows 'Braintrust missing API key' or a config warning">
  * Check `echo $BRAINTRUST_API_KEY`.
  * Validate the JSON syntax in `~/.pi/agent/braintrust.json` or `.pi/braintrust.json`.
  * Make sure `BRAINTRUST_ADDITIONAL_METADATA` contains valid JSON if you set it as an environment variable.
</Accordion>

<Accordion title="I want debug logs">
  Enable debug logging and restart pi:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  export BRAINTRUST_DEBUG=true
  ```

  You can also force file logging explicitly:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  export BRAINTRUST_LOG_FILE=true
  ```

  By default, logs are written under `~/.pi/agent/state/braintrust-pi-extension/`.
</Accordion>

<Accordion title="The trace link widget does not appear">
  * The widget is only shown in interactive mode.
  * Run at least one prompt so the extension has a trace to link to.
  * If tracing is active but no link appears, enable debug logging and inspect the extension log file.
</Accordion>

## Next steps

* **Explore the source**: See the [braintrust-pi-extension repository](https://github.com/braintrustdata/braintrust-pi-extension).
* **Run evaluations**: Check out the [evaluation guide](/evaluate/run-evaluations).
* **Inspect traces**: Open your Braintrust project in the [Braintrust UI](https://www.braintrust.dev/app).