> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# pi

> Trace pi coding sessions to Braintrust, including turns, model calls, tool executions, and compactions

[pi](https://pi.dev) is a minimal terminal coding harness. Connect it to Braintrust to trace your coding sessions.

<Note>
  This page documents pi sessions with the Braintrust extension. To trace `@earendil-works/pi-coding-agent` SDK usage in your own application, see [Pi Coding Agent SDK](/docs/integrations/agent-frameworks/pi-coding-agent).
</Note>

## Trace pi sessions

The [`@braintrust/pi-extension` extension](https://www.npmjs.com/package/@braintrust/pi-extension) passes your interactions with pi to `bt`, which in turn uses a background process to build and deliver the trace to Braintrust.

pi continues to communicate directly with its model provider, and tracing failures do not stop your pi session.

### Set up tracing

<Note>
  If `@braintrust/pi-extension` is already installed, follow [Update the tracing extension](#update-the-tracing-extension).
</Note>

<Steps>
  <Step title="Install pi">
    If you haven't already, install [pi](https://pi.dev/). The extension supports the latest patch release from each of the last five stable pi minor versions.
  </Step>

  <Step title="Install and authenticate bt">
    Follow the [`bt` CLI quickstart](/docs/reference/cli/quickstart) to install `bt` v0.19.3 or later, authenticate, and set your active context.
  </Step>

  <Step title="Enable tracing">
    <a id="settings" />

    Before starting pi, run this command in a terminal:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable pi --project <your-project>
    ```

    This command:

    * Installs (or updates) [`@braintrust/pi-extension`](https://www.npmjs.com/package/@braintrust/pi-extension) globally through pi's package installer, using the `^2` version range.
    * Writes `~/.pi/agent/braintrust.json`, which records whether tracing is enabled and which project receives traces.

    The tracing file stores settings, not credentials. A project's `.pi/braintrust.json` can override the global tracing settings.

    For more information, see [`bt trace enable`](/docs/reference/cli/trace#bt-trace-enable).
  </Step>

  <Step title="Restart pi">
    Restart pi so it loads the extension and tracing settings.
  </Step>

  <Step title="Log a test trace">
    Ask pi to do something simple. When the session finishes, open your Braintrust project and confirm that the trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page.
  </Step>
</Steps>

### What Braintrust traces

<a id="what-gets-traced" />

pi traces in Braintrust include:

* Session spans with the session ID, local username, Git repository metadata, and pi version when available.
* Turn spans with prompts, thinking level, and requested skills.
* Model call spans with conversation input, response output, errors, and token metrics.
* Tool spans with inputs and outputs, including skill loads when pi reads a `SKILL.md` file.
* Compaction spans for context compactions.
* Branch summary spans when pi summarizes a branch while navigating session history.

Every span records its origin as `braintrust.plugin.pi`.

### Common workflows

<AccordionGroup>
  <Accordion title="Use different tracing settings for one session">
    Use [`bt trace run`](/docs/reference/cli/trace#bt-trace-run) to trace a single pi invocation without changing the saved tracing configuration.

    This workflow launches pi from the terminal.

    To change the saved destination, profile, or organization, rerun [`bt trace enable pi`](/docs/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](/docs/reference/cli/switch) does not change the saved tracing configuration.

    To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace run` for one invocation or to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.

    With `bt` v0.19.3 or later, pass `--tag ci --tag release-validation` to either command to [tag session spans](/docs/reference/cli/trace#tag-traces).
  </Accordion>

  <Accordion title="Configure the tracing status display">
    In interactive sessions, pi shows a Braintrust status indicator and a trace-link widget. Both are enabled by default.

    To hide both displays, set `show_ui` to `false` in the global or project-local tracing file. To hide only the trace link, set `show_trace_link` to `false`. `BRAINTRUST_SHOW_UI` and `BRAINTRUST_SHOW_TRACE_LINK` override those settings.
  </Accordion>

  <Accordion title="Stop tracing pi sessions">
    Use [`bt trace disable pi`](/docs/reference/cli/trace#bt-trace-disable) to uninstall the global tracing extension and remove its global tracing configuration. Saved `bt` profiles and credentials are preserved. Restart pi afterward.

    Project-local extension installations and tracing files are separate. Remove any project-local installation too if you want to stop tracing there.
  </Accordion>
</AccordionGroup>

### Update the tracing extension

To update the extension, follow these steps:

<Note>
  If `pi list` shows `@braintrust/pi-extension` earlier than v2.0.0, or you cannot determine its version, follow [Migrate from an older extension version](#migrate-from-an-older-extension-version).
</Note>

<Steps>
  <Step title="Update bt">
    Follow the [CLI migration guide](/docs/reference/cli/migrate) to update `bt` to the latest version and complete the applicable migrations.
  </Step>

  <Step title="Update the tracing extension">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace update pi
    ```

    [`bt trace update`](/docs/reference/cli/trace#bt-trace-update) updates the installed extension without changing your saved tracing configuration.
  </Step>

  <Step title="Restart and verify pi">
    Restart pi, run a short session, and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.
  </Step>
</Steps>

### Migrate from an older extension version

<a id="upgrade" />

To migrate to the latest version of the `@braintrust/pi-extension` extension, follow these steps:

<Steps>
  <Step title="Inspect your pi extensions">
    Check whether `@braintrust/pi-extension` is installed:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    pi list
    ```

    Record the extension's starting version before updating. Also record the profile, organization, project, metadata, and custom tracing settings you want to preserve from the global tracing file and any project-local `.pi/braintrust.json`.

    <Note>
      If the extension is not installed, follow [Set up tracing](#set-up-tracing). If the output shows only a package version range and you cannot determine the installed version, complete both migration sections below.
    </Note>
  </Step>

  <Step title="Install or update bt">
    These steps require `bt` v0.19.3 or later. Check whether `bt` is installed:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt --version
    ```

    * If the command succeeds, [migrate to the latest version](/docs/reference/cli/migrate) (unless you've already done so).
    * Otherwise, [install `bt`](/docs/reference/cli/quickstart), authenticate, and set organization and project context.
  </Step>

  <Step title="Complete version-specific migration steps">
    <Note>
      Complete each section for a version newer than your starting `@braintrust/pi-extension` version, beginning with the oldest. If no sections apply, continue to the next step.
    </Note>

    <AccordionGroup>
      <Accordion title="@braintrust/pi-extension v1.0.0">
        <Note>
          Complete this section if you started your migration from an extension version earlier than v1.0.0.
        </Note>

        Before v1.0.0, the extension handled authentication and trace delivery itself. Starting in v1.0.0, `bt` handles both, and the tracing files store settings rather than credentials.

        Record `project`, `org_name`, and `additional_metadata` from `~/.pi/agent/braintrust.json` and your project's `.pi/braintrust.json`. Environment variables took precedence over these files. If the project was not configured, the default was `pi`.

        If the old configuration contains `api_key`, `api_url`, or `app_url`, use the corresponding credentials and deployment when you [authenticate with `bt`](/docs/reference/cli/login). Keep credentials private and retain any settings needed by other integrations.
      </Accordion>

      <Accordion title="@braintrust/pi-extension v2.0.0">
        <Note>
          Complete this section if you started your migration from an extension version earlier than v2.0.0.
        </Note>

        Before v2.0.0, the following environment variables overrode saved tracing settings. Starting in v2.0.0, the extension no longer reads these overrides from the agent's environment. Record any values you want to preserve:

        * `TRACE_TO_BRAINTRUST`: Whether tracing was enabled.
        * `BRAINTRUST_PROFILE` and `BRAINTRUST_ORG_NAME`: The tracing account and organization.
        * `BRAINTRUST_PROJECT`: The project that received traces.
        * `BRAINTRUST_ADDITIONAL_METADATA`: Extra root-span metadata.

        <Note>
          In the next step, pass the recorded project with `--project`, account and organization with `--profile` and `--org`, and metadata with `--additional-metadata '<JSON>'`. This preserves values that previously overrode your saved configuration.
        </Note>

        v2.0.0 also changes how conflicting settings in `braintrust.json` are resolved:

        * Profile, organization, and project values in the `route` object now take precedence over their legacy top-level equivalents. Before v2.0.0, the top-level values took precedence.
        * Metadata is unchanged: top-level `additional_metadata` can still override `route.additional_metadata`.

        The next step moves your saved settings into the `route` object so you do not leave conflicting copies. Environment variables accepted by `bt` commands are separate from these extension changes. See [`bt trace`](/docs/reference/cli/trace).
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Apply your tracing settings">
    Run this command with your intended project, using the project you recorded earlier to preserve your destination:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable pi --project <your-project>
    ```

    Pass `--profile <profile>` and `--org <organization>` if needed to preserve your tracing account and organization. Otherwise, the command uses your active `bt` context, not your saved tracing settings.

    The command updates your global tracing file, normally `~/.pi/agent/braintrust.json`. Check the following settings in that file:

    * Existing `route.additional_metadata` is preserved unless you pass `--additional-metadata`. If it is absent, `bt` migrates top-level `additional_metadata` instead.
    * Existing `route.tags` is preserved unless you pass `--tag` or set `BRAINTRUST_TAGS`.
    * `route.flush_mode` resets to `fire_and_forget`. Restore its previous value if you customized it.
    * Restore any other custom tracing settings you recorded before updating.

    The command also removes obsolete top-level destination and authentication keys from the global tracing file. It does not migrate project-local files. For each project-local file, use the `route` object in the generated global file as a template while preserving that project's intended destination, authentication, metadata, and tags. A project-level `route` object containing a `destination` replaces the entire global `route` object. After moving any legacy values under `route`, remove their duplicate top-level keys so they cannot override it.
  </Step>

  <Step title="Restart and verify pi">
    Restart pi, run a short session, and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project. Check each project where you changed local tracing settings.
  </Step>

  <Step title="Remove obsolete settings">
    <Note>
      Complete this step only if you started with an extension version earlier than v2.0.0 and verified that traces reach the intended project in the previous step.
    </Note>

    <Accordion title="Settings used before @braintrust/pi-extension v2.0.0">
      The extension now reads tracing settings from its configuration files. Environment variables you previously configured for tracing may no longer be needed.

      Check these locations for leftover settings:

      * Your shell configuration
      * The global tracing file and your project's `.pi/braintrust.json`

      Remove the settings below if they were used only for tracing. Keep any that other `bt` commands, MCP connections, or integrations still need:

      * `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, `BRAINTRUST_PROJECT`, and `BRAINTRUST_ADDITIONAL_METADATA` in the agent environment
      * `BRAINTRUST_API_KEY`, `BRAINTRUST_API_URL`, and `BRAINTRUST_APP_URL` used by pre-v1.0.0 tracing
      * Top-level `profile`, `org_name`, `project`, and `additional_metadata` after preserving their values under `route`
      * Pre-v1.0.0 `api_key`, `api_url`, `app_url`, `debug`, `log_file`, `state_dir`, `parent_span_id`, and `root_span_id` keys
      * Pre-v1.0.0 `BRAINTRUST_DEBUG`, `BRAINTRUST_LOG_FILE`, `BRAINTRUST_STATE_DIR`, `PI_PARENT_SPAN_ID`, and `PI_ROOT_SPAN_ID` environment variables

      Keep `BRAINTRUST_SHOW_UI` and `BRAINTRUST_SHOW_TRACE_LINK` if you use them to control the tracing display.
    </Accordion>
  </Step>
</Steps>

### Troubleshooting tracing

First, run `bt trace doctor pi`. Then, review the following:

<AccordionGroup>
  <Accordion title="The tracing extension is missing or disabled">
    Run `pi list` and confirm that `@braintrust/pi-extension` is installed. If it is missing or broken, run:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable pi --project <your-project>
    ```

    Restart pi afterward.
  </Accordion>

  <Accordion title="Traces do not appear after setup">
    If pi was running when its extension or configuration changed, restart it.

    Run `bt trace doctor pi` and confirm that tracing is enabled and routed to the intended project. Also inspect any project-local tracing file, which can override the global settings.

    If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](/docs/reference/cli/trace#project-log-permissions).

    For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](/docs/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](/docs/reference/cli/migrate#troubleshooting).

    Tracing failures do not interrupt the pi session.
  </Accordion>

  <Accordion title="pi uses an unexpected configuration directory">
    The global tracing file remains at `~/.pi/agent/braintrust.json`. The project-local file is normally `.pi/braintrust.json`. Its directory follows `piConfig.configDir` in the installed pi package's metadata, with `.pi` as the fallback.
  </Accordion>

  <Accordion title="Traces use unexpected settings">
    Invocation settings supplied by `bt trace run` take precedence over the saved tracing configuration.

    For normal sessions, project-local `.pi/braintrust.json` settings override global settings. A project-level `route` object containing a `destination` replaces the entire global `route` object, so include complete authentication settings too.

    The extension does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, `BRAINTRUST_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.

    If an older file still has top-level `additional_metadata`, migrate it to `route.additional_metadata` and remove the old key so it cannot override your intended metadata.

    For environment variables accepted by the `bt` commands themselves, see [`bt trace`](/docs/reference/cli/trace).
  </Accordion>
</AccordionGroup>

## Connect to Braintrust MCP

pi [does not include built-in MCP support](https://pi.dev/docs/latest/usage#design-principles). If you add MCP through a third-party adapter, follow the [Braintrust MCP client setup instructions](/docs/integrations/developer-tools/mcp#connect-your-client).

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](/docs/evaluate/run-evaluations).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](/docs/integrations/developer-tools/mcp#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).