Skip to main content
pi is a minimal terminal coding harness. The @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.

​
Trace pi sessions

The @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 to build and send traces to Braintrust.
  • Authentication happens through bt 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 for details.

​
Set up tracing

The extension requires @braintrust/pi-extension v1.0.0 or later, bt v0.16.0 or later, and pi v0.65.0 or later.
1

Install pi

If you haven’t already, install pi.
2

Install bt and authenticate

Tracing runs through bt, and the pi extension does not install it for you. Install the CLI and authenticate:
You can also install with mise or npm, or with PowerShell on Windows.
3

Configure the extension

After bt is installed and authenticated, run the following command:
4

Restart pi

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: <name>.
  • 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 saves your tracing configuration to ~/.pi/agent/braintrust.json. These saved settings control where traces go during normal pi sessions. 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 or BRAINTRUST_API_KEY. See credential precedence.
  • To use different settings for one launched session without changing saved configuration, use bt trace run.
  • To switch projects, re-run setup:

​
Common workflows

To apply custom settings to a single pi run, launch pi with bt trace run:
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 --:
To load the extension for a single session without installing it, use pi’s -e flag:
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.
1

Update bt

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. It explains how saved logins carry over, how profiles and organizations changed, and which commands replaced the old auth commands.
bt update updates installs made with the standalone shell or PowerShell installer. If you installed with mise or 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.
2

Authenticate bt

Starting in v1.0.0, @braintrust/pi-extension uses bt for tracing and authentication. If you haven’t authenticated with bt, run bt login. You can also authenticate with BRAINTRUST_API_KEY.
3

Run setup

Run setup with the Braintrust project that should receive your pi traces. This updates @braintrust/pi-extension and writes the latest tracing settings.
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.
4

Migrate settings from an extension version before v1.0.0

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:
For current settings and how to change them, see 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 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.

​
Connect to the Braintrust MCP server

Pi does not include built-in MCP support. If you add MCP to pi through a third-party adapter, you can connect to the Braintrust MCP server using the client setup instructions.

​
Next steps