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.

​
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
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
  • Turn spans: One span per user prompt / agent run
  • LLM spans: One span per model response inside a turn
  • Tool spans: One span per tool execution
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)
└── 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/braintrust.json
  4. Environment variables

​
Config file locations

  • Global: ~/.pi/agent/braintrust.json
  • Project: .pi/braintrust.json
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