@braintrust/pi-extension

Trace Pi sessions in Braintrust. The extension sends events to the local bt daemon, which builds and uploads traces. Pi keeps running if tracing fails.

What gets traced

• Session spans: one root span per Pi session with at least one turn
• Turn spans: one span per user prompt / agent run
• LLM spans: one span per model response inside a turn, with token usage, cache usage, reasoning tokens, estimated cost, time to first token, and the tool definitions available to that request. With a virtual model, the span names the physical model and thinking level that answered and records the selected virtual model as selected_model
• Tool spans: one span per tool execution, including dynamically loaded tools. Tool calls that another tool makes, such as a codemode script's tools.<name>() calls, are nested under the calling tool's span
• Compaction spans: one span per session compaction, including trigger/retry metadata when available
• Branch summary spans: one span per summarized /tree navigation branch

Trace shape:

Session (task)
├── Turn 1 (task)
│   ├── anthropic/claude-sonnet-4 (llm)
│   │   ├── read: package.json (tool)
│   │   └── bash: pnpm test (tool)
│   └── anthropic/claude-sonnet-4 (llm)
├── Compaction (task)
├── Branch Summary (task)
└── Turn 2 (task)

Quickstart

Install Pi and the Braintrust CLI, then run:

bt login
bt trace enable pi --project my-coding-agent
pi

This installs the extension and saves its configuration. Use --profile or --org to choose a profile or organization. Restart Pi if it is already open. The footer shows tracing status and a link to the trace when available.

To install the npm extension separately, use pi install npm:@braintrust/pi-extension, then configure tracing with bt trace enable pi.

For one invocation without changing global tracing configuration:

bt trace run --project my-coding-agent pi -- -p "summarize this repository"

The bt trace run routing and metadata flags also accept their matching BRAINTRUST_* environment variables; a plain pi session's extension does not. Historical import and live attach are not supported for Pi. Upgrading an active session from the pre-daemon extension is supported: when its local legacy state file is still present, the daemon continues the existing Braintrust root and turn sequence. If that state was removed or is invalid, tracing safely starts a new daemon session instead.

Compatibility

CI runs a traced Pi session with the packed extension against the latest patch from each of the last five stable Pi release lines. The compatibility job resolves these versions on each run, including releases from Pi's former npm package name when needed.

Configuration

Settings load in this order, with later values taking precedence:

1. Defaults
2. ~/.pi/agent/braintrust.json
3. .pi/braintrust.json in the project (or Pi's configured project config directory)
4. bt trace run settings for that invocation

Example:

{
  "trace_to_braintrust": true,
  "route": {
    "auth": { "profile": "work", "org_name": "acme" },
    "destination": { "type": "project_logs", "project_name": "pi" },
    "additional_metadata": { "team": "platform" }
  }
}

Settings

| Config key | Default | Purpose | |---|---|---| | trace_to_braintrust | false | Enable tracing | | route.auth.profile_id | unset | Saved profile ID written by bt setup | | route.auth.profile | default bt profile | Select a profile by name | | route.auth.org_name | profile default | Select an organization | | route.destination | project logs in pi | Select the trace destination | | route.additional_metadata | unset | Add root-span metadata | | route.flush_mode | flush_on_turn_end in the default route | Control delivery flushing | | show_ui | true | Show the status indicator; override with BRAINTRUST_SHOW_UI | | show_trace_link | true | Show the trace link; override with BRAINTRUST_SHOW_TRACE_LINK |

Older files can still use top-level profile, org_name, project, and additional_metadata. For new files, use bt trace enable or the nested route format above. Include a destination when supplying a route.

Only the display settings read environment variables directly. Tracing settings come from these files or bt trace run. Credentials are managed by bt.

Provider request metadata is limited to model, thinking, output-limit, and tool-count settings. Full provider payloads and thinking signatures are omitted.

Manage tracing

bt trace doctor pi
bt trace status
bt trace update pi
bt trace disable pi

Local development

From the monorepo root, build the extension before loading it locally:

make build-pi
pi -e ./dist/pi/dist/index.mjs

This loads the extension for one run; it still needs an enabled Braintrust configuration. Run make validate-pi for package checks. See the contribution guide for source development instructions.