Skip to main content
pi is a minimal terminal coding harness. The @braintrust/pi-extension package automatically traces pi sessions to Braintrust, including turns, model calls, and tool executions.
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.

​
Prerequisites

1

Install pi

If you haven’t already, install pi:
npm install -g @mariozechner/pi-coding-agent
2

Install the Braintrust extension

Install the package with pi:
pi install npm:@braintrust/pi-extension
Use the -l flag if you want a project-local install instead of a global one.
For a one-off run without installing it permanently, load the extension directly:
pi -e npm:@braintrust/pi-extension
This release supports pi v0.65.0 or later. On pi versions before 0.65.0, session switch and fork events are no longer traced.
3

Set your Braintrust environment variables

Tracing is disabled by default. Enable it and provide your API key:
export TRACE_TO_BRAINTRUST=true
export BRAINTRUST_API_KEY="YOUR_API_KEY"
export BRAINTRUST_PROJECT="pi"
Restart pi after changing environment variables.

​
Usage

Once enabled, the extension traces each pi session as a hierarchy of spans:
  • Session spans: One root span per pi session that produces at least one turn, with metadata capturing the session ID and name, hostname, username, operating system, working directory, repository, pi version, and extension version. At session close, the span records the total turn and tool-call counts and the close reason.
  • Turn spans: One span per user prompt or agent run. When pi fires an input event, turn spans also capture input_source, input_streaming_behavior, input_image_count, and raw_input (a truncated copy of the prompt text).
  • LLM spans: One span per model response inside a turn.
  • Tool spans: One span per tool execution.
  • Compaction spans: One span per context-window compaction, capturing the compaction reason, whether pi will retry, and the token counts before and after.
  • Branch Summary spans: One span each time pi summarizes a branch while navigating the session’s history tree, capturing the entries being condensed and the resulting summary.
Example trace structure: 
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)
In interactive mode, pi shows:
  • A Braintrust status indicator in the footer while tracing is active
  • A trace widget below the editor with a shortened clickable Braintrust trace link when available
To view traces, go to Logs in your Braintrust project.

​
Configuration

You can configure the extension with environment variables or JSON config files. Configuration precedence is:
  1. Defaults
  2. ~/.pi/agent/braintrust.json
  3. <pi-config-dir>/braintrust.json
  4. Environment variables

​
Config file locations

  • Global: ~/.pi/agent/braintrust.json
  • Project: <pi-config-dir>/braintrust.json, where <pi-config-dir> follows pi’s configured project directory and defaults to .pi.
The project config directory follows pi’s CONFIG_DIR_NAME setting, so a custom directory such as .custom-pi is used automatically. Older pi versions that don’t expose this setting always use .pi. The global config path (~/.pi/agent/braintrust.json) is not affected.
Example: 
{
  "trace_to_braintrust": true,
  "project": "pi",
  "debug": true,
  "additional_metadata": {
    "team": "platform"
  }
}

​
Supported settings

Config keyEnv varDefaultDescription
trace_to_braintrustTRACE_TO_BRAINTRUSTfalseEnable or disable tracing
api_keyBRAINTRUST_API_KEYunsetBraintrust API key
api_urlBRAINTRUST_API_URLhttps://api.braintrust.devBraintrust API base URL. For EU organizations, use https://api-eu.braintrust.dev. For self-hosted deployments, use your data plane URL.
app_urlBRAINTRUST_APP_URLhttps://www.braintrust.devBraintrust app URL
org_nameBRAINTRUST_ORG_NAMEunsetOrganization name for project-scoped links
projectBRAINTRUST_PROJECTpiBraintrust project that receives traces
debugBRAINTRUST_DEBUGfalseEnable debug logging
additional_metadataBRAINTRUST_ADDITIONAL_METADATA{}Extra metadata attached to session spans. When set via environment variable, pass a JSON object string.
log_fileBRAINTRUST_LOG_FILEunsetWrite extension logs to a file. Set to true or auto to use the default log path.
state_dirBRAINTRUST_STATE_DIR~/.pi/agent/state/braintrust-pi-extensionDirectory for extension session state and default logs
parent_span_idPI_PARENT_SPAN_IDunsetParent span ID for attaching pi traces under an existing trace
root_span_idPI_ROOT_SPAN_IDunsetRoot span ID to use when attaching to an existing trace

​
Embed traces in parent traces

You can attach a pi session under an existing Braintrust trace. This is useful when pi is part of a larger workflow and you want the entire interaction to appear inside a parent trace. To attach a pi session under an existing span, set PI_PARENT_SPAN_ID: 
export PI_PARENT_SPAN_ID="your-parent-span-id"
pi
When the parent span is not the trace root, also set PI_ROOT_SPAN_ID: 
export PI_PARENT_SPAN_ID="parent-span-id"
export PI_ROOT_SPAN_ID="root-span-id"
pi

​
Troubleshooting

  • Verify TRACE_TO_BRAINTRUST=true.
  • Verify BRAINTRUST_API_KEY is set in the shell where you launch pi.
  • Restart pi after changing environment variables or config files.
  • Run at least one prompt. A session root span is only created for sessions that actually produce a turn.
  • Check echo $BRAINTRUST_API_KEY.
  • Validate the JSON syntax in ~/.pi/agent/braintrust.json or .pi/braintrust.json.
  • Make sure BRAINTRUST_ADDITIONAL_METADATA contains valid JSON if you set it as an environment variable.
Enable debug logging and restart pi:
export BRAINTRUST_DEBUG=true
You can also force file logging explicitly:
export BRAINTRUST_LOG_FILE=true
By default, logs are written under ~/.pi/agent/state/braintrust-pi-extension/.

​
Next steps