pi - Braintrust

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

Install pi

If you haven’t already, install pi:

npm install -g @mariozechner/pi-coding-agent

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.

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, Git remote origin URL (with credentials redacted), current Git branch, HEAD commit hash, 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). When the prompt includes explicit /skill:<name> requests, turn spans also record loaded_skill_names and loaded_skills.
LLM spans: One span per model response inside a turn. Spans record the model name, stop reason, token metrics (prompt, completion, cached, and reasoning tokens), and streaming timing metrics. When the model provides capability metadata, spans also capture model_context_window, model_max_tokens, model_supports_reasoning, supported_thinking_levels, and deferred_tools_mode. Provider request metadata includes provider_request_tool_count and provider_request_deferred_tool_count.
Tool spans: One span per tool execution. When pi reads a SKILL.md file, the span is renamed to skill: <skill-name> and carries skill_name and skill_path metadata. If the skill was explicitly requested via /skill:<name> in the prompt, the span also includes skill_load_trigger: "explicit".
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:

Defaults
~/.pi/agent/braintrust.json
<pi-config-dir>/braintrust.json
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 key	Env var	Default	Description
`trace_to_braintrust`	`TRACE_TO_BRAINTRUST`	`false`	Enable or disable tracing
`api_key`	`BRAINTRUST_API_KEY`	unset	Braintrust API key
`api_url`	`BRAINTRUST_API_URL`	`https://api.braintrust.dev`	Braintrust API base URL. For EU organizations, use `https://api-eu.braintrust.dev`. For self-hosted deployments, use your data plane URL.
`app_url`	`BRAINTRUST_APP_URL`	`https://www.braintrust.dev`	Braintrust app URL
`org_name`	`BRAINTRUST_ORG_NAME`	unset	Organization name for project-scoped links
`project`	`BRAINTRUST_PROJECT`	`pi`	Braintrust project that receives traces
`debug`	`BRAINTRUST_DEBUG`	`false`	Enable debug logging
`additional_metadata`	`BRAINTRUST_ADDITIONAL_METADATA`	`{}`	Extra metadata attached to session spans. When set via environment variable, pass a JSON object string.
`log_file`	`BRAINTRUST_LOG_FILE`	unset	Write extension logs to a file. Set to `true` or `auto` to use the default log path.
`state_dir`	`BRAINTRUST_STATE_DIR`	`~/.pi/agent/state/braintrust-pi-extension`	Directory for extension session state and default logs
`parent_span_id`	`PI_PARENT_SPAN_ID`	unset	Parent span ID for attaching pi traces under an existing trace
`root_span_id`	`PI_ROOT_SPAN_ID`	unset	Root 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

No traces are appearing

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.

pi shows 'Braintrust missing API key' or a config warning

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.

I want debug logs

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/.

The trace link widget does not appear

Next steps

Explore the source: See the braintrust-pi-extension repository.
Run evaluations: Check out the evaluation guide.
Inspect traces: Open your Braintrust project in the Braintrust UI.

AI providers

SDKs

Developer tools

pi

Prerequisites

Usage

Configuration

Config file locations

Supported settings

Embed traces in parent traces

Troubleshooting

Next steps

​Prerequisites

​Usage

​Configuration

​Config file locations

​Supported settings

​Embed traces in parent traces

​Troubleshooting

​Next steps

Prerequisites

Usage

Configuration

Config file locations

Supported settings

Embed traces in parent traces

Troubleshooting

Next steps