> ## 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.
If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/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, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.
[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.