> ## 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
> Trace pi coding sessions to Braintrust with the pi-extension package, including turns, model calls, tool executions, and compactions.
[pi](https://pi.dev) is a minimal terminal coding harness. The [`@braintrust/pi-extension`](https://www.npmjs.com/package/@braintrust/pi-extension) package traces pi sessions to Braintrust, including turns, model calls, tool executions, and compactions.
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](/docs/integrations/agent-frameworks/pi-coding-agent).
## Trace pi sessions
The [`@braintrust/pi-extension`](https://www.npmjs.com/package/@braintrust/pi-extension) package traces pi sessions to Braintrust by observing pi, not by proxying it:
* Pi talks to its model provider directly.
* Native events notify the extension when sessions start, turns run, models respond, and tools execute.
* The extension uses the [`bt` CLI](/docs/reference/cli/trace) to build and send traces to Braintrust.
* Authentication happens through [`bt login`](/docs/reference/cli/login). The extension never handles credentials.
* If the extension or `bt` has a problem, pi keeps working. However, you won't see traces until the setup is fixed.
Each pi session appears in Braintrust as one trace with session, turn, model call, and tool spans. See [What gets traced](#what-gets-traced) for details.
### Set up tracing
The extension requires [`@braintrust/pi-extension`](https://www.npmjs.com/package/@braintrust/pi-extension) v1.0.0 or later, [`bt`](https://github.com/braintrustdata/bt) v0.16.0 or later, and pi v0.65.0 or later.
If you haven't already, install [pi](https://pi.dev/).
Tracing runs through `bt`, and the pi extension does not install it for you. [Install the CLI](/docs/reference/cli/quickstart#install) and [authenticate](/docs/reference/cli/quickstart#authenticate-and-set-context):
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl -fsSL https://bt.dev/cli/install.sh | bash
bt login
```
You can also install with [mise](/docs/reference/cli/quickstart#install-with-mise) or [npm](/docs/reference/cli/quickstart#install-with-npm), or with [PowerShell on Windows](/docs/reference/cli/quickstart#install).
After `bt` is installed and authenticated, run the following command:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace setup pi --project my-project # Replace with your project name
```
Restart pi so it loads the extension.
### What gets traced
pi traces in Braintrust include:
* Session spans with `session_id`, `source`, pi version, and Git repository metadata.
* Turn spans with prompts, model names, thinking level, and `loaded_skill_names` when the prompt requests skills.
* Model call spans with conversation input, response output, errors, and token metrics.
* Tool spans with tool inputs and outputs. When pi runs the `skill` tool, the span is named `skill: `.
* Compaction spans (`Compaction`) for context-window compactions.
* Branch summary spans (`Branch Summary`) when pi summarizes a branch while navigating the session's history tree.
The root span records pi and extension metadata, including the extension version.
### Settings
[`bt trace setup pi`](/docs/reference/cli/trace#bt-trace-setup) saves your tracing configuration to `~/.pi/agent/braintrust.json`. These saved settings control where traces go during normal pi sessions.
| Setting | Saved key | How to change it |
| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable tracing | `trace_to_braintrust` | Set `trace_to_braintrust` to `true` or `false` in the config file. Re-running `bt trace setup pi` also re-enables tracing. Env var `TRACE_TO_BRAINTRUST` overrides the saved value. |
| Project | `route.destination` | Re-run `bt trace setup pi` with `--project`. Env var `BRAINTRUST_PROJECT` overrides the saved value. |
| `bt` profile | `route.auth.profile` | Re-run `bt trace setup pi` with `--profile` (the profile must already be logged in with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context)). Env var `BRAINTRUST_PROFILE` overrides the saved value. |
| Organization | `route.auth.org_name` | Re-run `bt trace setup pi` with `--org`. Env var `BRAINTRUST_ORG_NAME` overrides the saved value. |
| Extra span metadata | `route.additional_metadata` | Edit `route.additional_metadata` in the config file to save metadata. Env var `BRAINTRUST_ADDITIONAL_METADATA` overrides the saved value. |
| Status indicator | `show_ui` | Set `show_ui` to `true` or `false` in the config file. On by default. Env var `BRAINTRUST_SHOW_UI` overrides the saved value. |
| Trace link widget | `show_trace_link` | Set `show_trace_link` to `true` or `false` in the config file. On by default. Env var `BRAINTRUST_SHOW_TRACE_LINK` overrides the saved value. |
Notes:
* For pi tracing, environment variables override saved settings. The project config (`.pi/braintrust.json`) overrides the global config (`~/.pi/agent/braintrust.json`). The project config directory follows pi's `CONFIG_DIR_NAME` setting.
* Credentials are stored by `bt`, not the configuration file. Authenticate with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context) or `BRAINTRUST_API_KEY`. See [credential precedence](/docs/reference/cli/overview#credential-precedence).
* To use different settings for one launched session without changing saved configuration, use [`bt trace run`](/docs/reference/cli/trace#bt-trace-run).
* To switch projects, re-run setup:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace setup pi --project another-project
```
### Common workflows
To apply custom settings to a single pi run, launch pi with [`bt trace run`](/docs/reference/cli/trace#bt-trace-run):
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace run --project scratch-project pi
```
`bt trace run` automatically injects the extension (via pi's `-e` flag), so the extension does not need to be installed globally. This command can send one run to a different project, profile, or organization without changing the saved settings in `~/.pi/agent/braintrust.json`.
To run pi non-interactively, pass its `-p` flag after `--`:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace run --project scratch-project pi -- -p "summarize this repo"
```
To load the extension for a single session without installing it, use pi's `-e` flag:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pi -e npm:@braintrust/pi-extension
```
This uses your saved tracing settings from `~/.pi/agent/braintrust.json` but does not permanently install the extension.
### Upgrade
To get the latest `bt` and `@braintrust/pi-extension`, follow these steps. If you are upgrading from `@braintrust/pi-extension` before v1.0.0, the steps also cover the required migration.
Update `bt` before updating `@braintrust/pi-extension`.
If you're also migrating from an older `bt` version with `bt auth` commands, review the [CLI migration guide](/docs/reference/cli/migrate). It explains how saved logins carry over, how profiles and organizations changed, and which commands replaced the old auth commands.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt update
```
`bt update` updates installs made with the standalone shell or PowerShell installer. If you installed with [mise](/docs/reference/cli/quickstart#install-with-mise) or [npm](/docs/reference/cli/quickstart#install-with-npm), update `bt` with that package manager instead. If a Windows install older than `bt` v0.17.0 cannot update itself, rerun the [PowerShell installer](/docs/reference/cli/quickstart#install).
Starting in v1.0.0, `@braintrust/pi-extension` uses `bt` for tracing and authentication. If you haven't authenticated with `bt`, run [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context). You can also authenticate with `BRAINTRUST_API_KEY`.
Run setup with the Braintrust project that should receive your pi traces. This updates `@braintrust/pi-extension` and writes the latest tracing settings.
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace setup pi --project my-project # Replace with your project name
```
Before v1.0.0, the extension read the destination project from the `BRAINTRUST_PROJECT` environment variable or the top-level `project` key in `~/.pi/agent/braintrust.json` or your project's `.pi/braintrust.json`. If you are upgrading from one of these versions, find the old value. In the command above, replace `my-project` with that value. `bt trace setup` does not migrate the old top-level key automatically.
If you are upgrading from an extension version before v1.0.0, use this table to migrate environment variables and settings from `~/.pi/agent/braintrust.json` or your project's `.pi/braintrust.json`:
| Before v1.0.0 | Starting in v1.0.0 |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BRAINTRUST_API_KEY` | Authentication happens through `bt`. Use [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context), or continue using `BRAINTRUST_API_KEY`. |
| `api_key`, `api_url`, `app_url`, `log_file`, `state_dir` in `~/.pi/agent/braintrust.json` or `.pi/braintrust.json` | Remove these keys. The extension no longer reads them. |
| Top-level `project`, `profile`, `org_name` in `~/.pi/agent/braintrust.json` or `.pi/braintrust.json` | Pass their values to `bt trace setup pi` with `--project`, `--profile`, and `--org` as needed, then remove the old top-level keys. Setup saves the new values under `route` in `~/.pi/agent/braintrust.json`. |
| `PI_PARENT_SPAN_ID`, `PI_ROOT_SPAN_ID` | Remove these variables. The extension no longer reads them. There is no documented pi replacement for embedding a session under an existing trace. |
For current settings and how to change them, see [Settings](#settings).
### Troubleshooting
Check the following, in order:
* Verify `bt` is installed and current: `bt --version` (v0.16.0 or later).
* Verify `bt` is authenticated: run `bt status`. Authenticate with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context) or `BRAINTRUST_API_KEY`.
* Verify the extension is installed: run `pi list` and check for `@braintrust/pi-extension`.
* Verify tracing is enabled: re-run `bt trace setup pi` to set `trace_to_braintrust` to `true`.
* Restart pi after any configuration change.
* Run at least one prompt. A session root span is only created for sessions that actually produce a turn.
Tracing failures don't interrupt pi, so your pi session can keep working even when traces do not appear.
* The widget is only shown in interactive mode.
* Run at least one prompt so the extension has a trace to link to.
* Check that `show_trace_link` is not set to `false`.
## Connect to the Braintrust MCP server
Pi [does not include built-in MCP support](https://pi.dev/docs/latest/usage#design-principles). If you add MCP to pi through a third-party adapter, you can connect to the Braintrust MCP server using the [client setup instructions](/docs/integrations/developer-tools/mcp#connect-your-client).
## Next steps
* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace), including setup and per-run tracing.
* **Run evaluations**: Check out the [evaluation guide](/docs/evaluate/run-evaluations) to learn evaluation patterns.
* **Explore MCP tools**: See the [MCP documentation](/docs/integrations/developer-tools/mcp#tools) for all available commands.
* **Browse the source**: The [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins) contains the extension source code.