> ## 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
    ```
  </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
* **Turn spans**: One span per user prompt / agent run
* **LLM spans**: One span per model response inside a turn
* **Tool spans**: One span per tool execution

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)
└── 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/braintrust.json`
4. Environment variables

### Config file locations

* Global: `~/.pi/agent/braintrust.json`
* Project: `.pi/braintrust.json`

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).