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

# pi

> Trace your pi coding sessions to Braintrust and use the Braintrust MCP server to query projects, experiments, logs, and datasets from pi

[pi](https://pi.dev) is a minimal terminal coding harness. You can connect it to Braintrust in two ways:

* **Trace pi sessions** to record turn, model call, tool execution, and compaction spans in Braintrust.
* **Connect to Braintrust MCP** to work with Braintrust projects, experiments, logs, and other data from pi.

> [!NOTE]
>
> This page documents pi sessions with the Braintrust extension. To trace `@earendil-works/pi-coding-agent` SDK usage in your own application, see [Pi Coding Agent SDK](https://docs.braintrust.dev/integrations/agent-frameworks/pi-coding-agent.md).

## Trace pi sessions

The [`@braintrust/pi-extension` extension](https://www.npmjs.com/package/@braintrust/pi-extension) uses `bt` to trace your pi sessions to Braintrust.

### Set up tracing

> [!NOTE]
>
> If `@braintrust/pi-extension` is already installed, follow [Update the tracing extension](#update-the-tracing-extension).

**1. Install pi**

If you haven't already, install [pi](https://pi.dev/). The extension supports the latest patch release from each of the last five stable pi minor versions.

**2. Install and authenticate bt**

Follow the [`bt` CLI quickstart](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt` v0.19.3 or later, authenticate, and set your active context.

**3. Enable tracing**

Before starting pi, run this command in a terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable pi --project <your-project>
```

This command:

* Installs (or updates) [`@braintrust/pi-extension`](https://www.npmjs.com/package/@braintrust/pi-extension) globally through pi's package installer.
* Writes `~/.pi/agent/braintrust.json`, which records whether tracing is enabled and which project receives traces.

The tracing file stores settings, not credentials. A project's `.pi/braintrust.json` can override the global tracing settings.

For more information, see [`bt trace enable`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable).

**4. Restart pi**

Restart pi so it loads the extension and tracing settings.

**5. Log a test trace**

Ask pi to do something simple. When the session finishes, open your Braintrust project and confirm that the trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page.

### What Braintrust traces

pi traces in Braintrust include:

* Session spans with the session ID, local username, working directory, selected model, Git repository metadata, pi version when available, the running pi package name in `metadata.host_name`, and the final response of the last completed turn.
* Turn spans with prompts, final responses, thinking level, and requested skills. Turns that end in an error or are aborted have no final response.
* Model call spans with conversation input, response output, errors, token metrics, the thinking level used for the response, and request settings and tool definitions when available. When a virtual model answers with a different model, `selected_model` records the model you selected.
* Tool spans with inputs, outputs, and errors, including skill loads when pi reads a `SKILL.md` file. Tool calls made by codemode scripts nest under the codemode tool span.
* Compaction spans for context compactions.
* Branch summary spans when pi summarizes a branch while navigating session history.

Every span records its origin as `braintrust.plugin.pi`, along with versions in `context.span_origin`: the plugin version in `version`, the `bt` version in `bt.version`, and the pi version in `pi.version`. These versions are captured when each span is created, and unknown versions are `null`. Each turn span and every span under it records the turn's span ID in `metadata.turn_span_id`.

### Common workflows

> [accordion] Use different tracing settings for one session
>
> Use [`bt trace run`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-run) to trace a single pi invocation without changing the saved tracing configuration.
>
> This workflow launches pi from the terminal.
>
> To change the saved destination, profile, or organization, rerun [`bt trace enable pi`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/reference/cli/switch) does not change the saved tracing configuration.
>
> To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace run` for one invocation or to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.
>
> With `bt` v0.19.3 or later, pass `--tag ci --tag release-validation` to either command to [tag session spans](https://docs.braintrust.dev/reference/cli/trace.md#tag-traces).

> [accordion] Configure the tracing status display
>
> In interactive sessions, pi shows a Braintrust status indicator and a trace-link widget. Both are enabled by default.
>
> To hide both displays, set `show_ui` to `false` in the global or project-local tracing file. To hide only the trace link, set `show_trace_link` to `false`. `BRAINTRUST_SHOW_UI` and `BRAINTRUST_SHOW_TRACE_LINK` override those settings.

> [accordion] Stop tracing pi sessions
>
> Use [`bt trace disable pi`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-disable) to uninstall the global tracing extension and remove its global tracing configuration. Saved `bt` profiles and credentials are preserved. Restart pi afterward.
>
> Project-local extension installations and tracing files are separate. Remove any project-local installation too if you want to stop tracing there.

### Update the tracing extension

To update the extension, follow these steps:

> [!NOTE]
>
> If `pi list` shows `@braintrust/pi-extension` earlier than v2.0.0, or you cannot determine its version, follow [Migrate from an older extension version](#migrate-from-an-older-extension-version).

**1. Update bt**

Follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations.

**2. Update the tracing extension**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update pi
```

[`bt trace update`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-update) updates the installed extension without changing your saved tracing configuration.

**3. Restart and verify pi**

Restart pi, run a short session, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

### Migrate from an older extension version

To migrate to the latest version of the `@braintrust/pi-extension` extension, follow these steps:

**1. Inspect your pi extensions**

Check whether `@braintrust/pi-extension` is installed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pi list
```

Record the extension's starting version before updating. Also record the profile, organization, project, metadata, and custom tracing settings you want to preserve from the global tracing file and any project-local `.pi/braintrust.json`.

> [!NOTE]
>
> If the extension is not installed, follow [Set up tracing](#set-up-tracing). If the output shows only a package version range and you cannot determine the installed version, complete both migration sections below.

**2. Install or update bt**

These steps require `bt` v0.19.3 or later. Check whether `bt` is installed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt --version
```

* If the command succeeds, [migrate to the latest version](https://docs.braintrust.dev/reference/cli/migrate.md) (unless you've already done so).
* Otherwise, [install `bt`](https://docs.braintrust.dev/reference/cli/quickstart), authenticate, and set organization and project context.

**3. Complete version-specific migration steps**

> [!NOTE]
>
> Complete each section for a version newer than your starting `@braintrust/pi-extension` version, beginning with the oldest. If no sections apply, continue to the next step.

> [accordion] @braintrust/pi-extension v1.0.0
>
> > [!NOTE]
> >
> > Complete this section if you started your migration from an extension version earlier than v1.0.0.
>
> Before v1.0.0, the extension handled authentication and trace delivery itself. Starting in v1.0.0, `bt` handles both, and the tracing files store settings rather than credentials.
>
> Record `project`, `org_name`, and `additional_metadata` from `~/.pi/agent/braintrust.json` and your project's `.pi/braintrust.json`. Environment variables took precedence over these files. If the project was not configured, the default was `pi`.
>
> If the old configuration contains `api_key`, `api_url`, or `app_url`, use the corresponding credentials and deployment when you [authenticate with `bt`](https://docs.braintrust.dev/reference/cli/login). Keep credentials private and retain any settings needed by other integrations.

> [accordion] @braintrust/pi-extension v2.0.0
>
> > [!NOTE]
> >
> > Complete this section if you started your migration from an extension version earlier than v2.0.0.
>
> Before v2.0.0, the following environment variables overrode saved tracing settings. Starting in v2.0.0, the extension no longer reads these overrides from the agent's environment. Record any values you want to preserve:
>
> * `TRACE_TO_BRAINTRUST`: Whether tracing was enabled.
>
> * `BRAINTRUST_PROFILE` and `BRAINTRUST_ORG_NAME`: The tracing account and organization.
>
> * `BRAINTRUST_PROJECT`: The project that received traces.
>
> * `BRAINTRUST_ADDITIONAL_METADATA`: Extra root-span metadata.
>
> > [!NOTE]
> >
> > In the next step, pass the recorded project with `--project`, account and organization with `--profile` and `--org`, and metadata with `--additional-metadata '<JSON>'`. This preserves values that previously overrode your saved configuration.
>
> v2.0.0 also changes how conflicting settings in `braintrust.json` are resolved:
>
> * Profile, organization, and project values in the `route` object now take precedence over their legacy top-level equivalents. Before v2.0.0, the top-level values took precedence.
> * Metadata is unchanged: top-level `additional_metadata` can still override `route.additional_metadata`.
>
> The next step moves your saved settings into the `route` object so you do not leave conflicting copies. Environment variables accepted by `bt` commands are separate from these extension changes. See [`bt trace`](https://docs.braintrust.dev/reference/cli/trace).

**4. Apply your tracing settings**

Run this command with your intended project, using the project you recorded earlier to preserve your destination:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable pi --project <your-project>
```

Pass `--profile <profile>` and `--org <organization>` if needed to preserve your tracing account and organization. Otherwise, the command uses your active `bt` context, not your saved tracing settings.

The command updates your global tracing file, normally `~/.pi/agent/braintrust.json`. Check the following settings in that file:

* Existing `route.additional_metadata` is preserved unless you pass `--additional-metadata`. If it is absent, `bt` migrates top-level `additional_metadata` instead.
* Existing `route.tags` is preserved unless you pass `--tag` or set `BRAINTRUST_TAGS`.
* `route.flush_mode` resets to `fire_and_forget`. Restore its previous value if you customized it.
* Restore any other custom tracing settings you recorded before updating.

The command also removes obsolete top-level destination and authentication keys from the global tracing file. It does not migrate project-local files. For each project-local file, use the `route` object in the generated global file as a template while preserving that project's intended destination, authentication, metadata, and tags. A project-level `route` object containing a `destination` replaces the entire global `route` object. After moving any legacy values under `route`, remove their duplicate top-level keys so they cannot override it.

**5. Restart and verify pi**

Restart pi, run a short session, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project. Check each project where you changed local tracing settings.

**6. Remove obsolete settings**

> [!NOTE]
>
> Complete this step only if you started with an extension version earlier than v2.0.0 and verified that traces reach the intended project in the previous step.

> [accordion] Settings used before @braintrust/pi-extension v2.0.0
>
> The extension now reads tracing settings from its configuration files. Environment variables you previously configured for tracing may no longer be needed.
>
> Check these locations for leftover settings:
>
> * Your shell configuration
> * The global tracing file and your project's `.pi/braintrust.json`
>
> Remove the settings below if they were used only for tracing. Keep any that other `bt` commands, MCP connections, or integrations still need:
>
> * `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, `BRAINTRUST_PROJECT`, and `BRAINTRUST_ADDITIONAL_METADATA` in the agent environment
> * `BRAINTRUST_API_KEY`, `BRAINTRUST_API_URL`, and `BRAINTRUST_APP_URL` used by pre-v1.0.0 tracing
> * Top-level `profile`, `org_name`, `project`, and `additional_metadata` after preserving their values under `route`
> * Pre-v1.0.0 `api_key`, `api_url`, `app_url`, `debug`, `log_file`, `state_dir`, `parent_span_id`, and `root_span_id` keys
> * Pre-v1.0.0 `BRAINTRUST_DEBUG`, `BRAINTRUST_LOG_FILE`, `BRAINTRUST_STATE_DIR`, `PI_PARENT_SPAN_ID`, and `PI_ROOT_SPAN_ID` environment variables
>
> Keep `BRAINTRUST_SHOW_UI` and `BRAINTRUST_SHOW_TRACE_LINK` if you use them to control the tracing display.

### Troubleshooting tracing

First, run `bt trace doctor pi`. Then, review the following:

> [accordion] The tracing extension is missing or disabled
>
> Run `pi list` and confirm that `@braintrust/pi-extension` is installed. If it is missing or broken, run:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace enable pi --project <your-project>
> ```
>
> Restart pi afterward.

> [accordion] Traces do not appear after setup
>
> If pi was running when its extension or configuration changed, restart it.
>
> Run `bt trace doctor pi` and confirm that tracing is enabled and routed to the intended project. Also inspect any project-local tracing file, which can override the global settings.
>
> If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](https://docs.braintrust.dev/reference/cli/migrate.md#troubleshooting).
>
> Tracing failures do not interrupt the pi session.

> [accordion] pi uses an unexpected configuration directory
>
> The global tracing file remains at `~/.pi/agent/braintrust.json`. The project-local file is normally `.pi/braintrust.json`. Its directory follows `piConfig.configDir` in the running pi package's metadata, with `.pi` as the fallback.

> [accordion] Traces use unexpected settings
>
> Invocation settings supplied by `bt trace run` take precedence over the saved tracing configuration.
>
> For normal sessions, project-local `.pi/braintrust.json` settings override global settings. A project-level `route` object containing a `destination` replaces the entire global `route` object, so include complete authentication settings too.
>
> The extension does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, `BRAINTRUST_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.
>
> If an older file still has top-level `additional_metadata`, migrate it to `route.additional_metadata` and remove the old key so it cannot override your intended metadata.
>
> For environment variables accepted by the `bt` commands themselves, see [`bt trace`](https://docs.braintrust.dev/reference/cli/trace).

## Connect to Braintrust MCP

The Braintrust MCP server lets pi query and update Braintrust data. MCP is configured independently from the tracing extension.

**1. Choose authentication**

> [tab] OAuth (recommended)
>
> Use OAuth when your client supports it. Your client opens a Braintrust authorization page where you sign in and approve access. The server acts with the permissions of the account you sign in with.
>
> * No Braintrust API key required
> * No OAuth client ID or client secret to configure
>
> The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at `/.well-known/oauth-authorization-server` on the same host as your MCP endpoint (see next step), so a client can register itself.

> [tab] API key
>
> Use an API key for clients without OAuth support or for programmatic connections. The server acts with the permissions of the account the key belongs to.
>
> 1. Create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
> 2. Configure your client to send this header on every request, replacing `YOUR_BRAINTRUST_API_KEY` with your key:
>
>    ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
>    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
>    ```

> [!NOTE]
>
> Your [`bt login`](https://docs.braintrust.dev/reference/cli/login) doesn't authenticate the MCP server.

**2. Choose your endpoint**

Use the endpoint for your organization's [data plane region](https://docs.braintrust.dev/admin/organizations.md#data-plane-region):

| Region | MCP endpoint |
| - | - |
| US | `https://api.braintrust.dev/mcp` |
| EU | `https://api-eu.braintrust.dev/mcp` |

Other connection details:

* **Self-hosted:** Copy the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane). This is your Braintrust API URL with `/mcp` appended.
* **Transport:** If your client asks you to choose a transport, choose HTTP (also called streamable HTTP). SSE-only clients can't connect.

**3. Add the server to pi**

MCP requires pi v1.0.0 or later. Earlier versions don't include built-in MCP support.

Follow the [pi guide](https://pi.dev/docs/latest/mcp#configure-servers) to add the remote server.

**4. Verify the connection**

To verify the connection, ask pi to list your recent Braintrust projects. If it can't connect, see [Braintrust MCP troubleshooting](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#troubleshooting).

**5. Start using Braintrust tools**

pi can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:

* "Show me my recent Braintrust experiments."
* "Query the last 10 logged requests with errors."
* "Compare accuracy scores between my two latest experiments."

See [what the Braintrust MCP can do](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](https://docs.braintrust.dev/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](https://docs.braintrust.dev/evaluate/run-evaluations.md).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.