Skip to main content
pi is a minimal terminal coding harness. Connect it to Braintrust to trace your coding sessions.
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.

​
Trace pi sessions

The @braintrust/pi-extension extension passes your interactions with pi to bt, which in turn uses a background process to build and deliver the trace to Braintrust. pi continues to communicate directly with its model provider, and tracing failures do not stop your pi session.

​
Set up tracing

If @braintrust/pi-extension is already installed, follow Update the tracing extension.
1

Install pi

If you haven’t already, install pi. 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 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:
This command:
  • Installs (or updates) @braintrust/pi-extension globally through pi’s package installer, using the ^2 version range.
  • 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.
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 page.

​
What Braintrust traces

pi traces in Braintrust include:
  • Session spans with the session ID, local username, Git repository metadata, and pi version when available.
  • Turn spans with prompts, thinking level, and requested skills.
  • Model call spans with conversation input, response output, errors, and token metrics.
  • Tool spans with inputs and outputs, including skill loads when pi reads a SKILL.md file.
  • 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.

​
Common workflows

Use 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 with the corresponding options. Running bt 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.
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.
Use bt trace disable pi 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:
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.
1

Update bt

Follow the CLI migration guide to update bt to the latest version and complete the applicable migrations.
2

Update the tracing extension

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 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:
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.
If the extension is not installed, follow 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:
3

Complete version-specific migration steps

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.
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. Keep credentials private and retain any settings needed by other integrations.
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.
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.
4

Apply your tracing settings

Run this command with your intended project, using the project you recorded earlier to preserve your destination:
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 page in the intended Braintrust project. Check each project where you changed local tracing settings.
6

Remove obsolete settings

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.
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:
Run pi list and confirm that @braintrust/pi-extension is installed. If it is missing or broken, run:
Restart pi afterward.
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.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting and the CLI migration troubleshooting guide.Tracing failures do not interrupt the pi session.
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 installed pi package’s metadata, with .pi as the fallback.
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.

​
Connect to Braintrust MCP

pi does not include built-in MCP support. If you add MCP through a third-party adapter, follow the Braintrust MCP client setup instructions.

​
Next steps