@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
/treenavigation 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.
Package detection prefers the running CLI to an extension-local peer dependency.
Pi-compatible hosts are recognized by a piConfig field or a known package name,
including Oh My Pi (@oh-my-pi/pi-coding-agent). The trace records the host
package name in metadata.host_name and its version in metadata.pi_version.
Configuration
Settings load in this order, with later values taking precedence:
- Defaults
~/.pi/agent/braintrust.json.pi/braintrust.jsonin the project (or Pi's configured project config directory)bt trace runsettings 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.