bt trace - Braintrust

bt trace connects a coding agent to Braintrust so its sessions are traced: every session, conversation turn, model call, and tool use lands in a Braintrust project. It requires bt v0.16.0 or later and supports Claude Code, Codex, OpenCode, and pi. Tracing works by observation. The agent’s Braintrust plugin doesn’t sit in between your agent and its model provider. Instead, it observes the agent’s hooks or native events and hands trace events to bt, which relays them to a background process (the tracing daemon) that builds the trace and delivers it to Braintrust. The plugin never handles credentials: authentication happens through bt, using the same login or API key as any other bt command, so there is nothing separate to configure for tracing. Tracing also never gets in your agent’s way. If any part of the chain is missing or broken, the agent keeps working normally. You just don’t see traces until it’s fixed.

bt trace setup

Set up persistent tracing for an agent. One command installs the agent’s Braintrust tracing plugin, selects a project, and turns tracing on:

bt trace setup claude --project my-project   # Replace with your project name

The agent argument is one of claude, codex, opencode, or pi. What “install” means depends on the agent (see the full setup guides for Claude Code, Codex, OpenCode, and pi):

Agent	What setup does
`claude`	Adds the Braintrust plugin marketplace and installs `trace-claude-code` through Claude Code’s plugin manager
`codex`	Adds the Braintrust plugin marketplace and installs `trace-codex` through Codex’s plugin manager
`opencode`	Adds `@braintrust/trace-opencode` to your OpenCode configuration file
`pi`	Runs `pi install` for `@braintrust/pi-extension`

In every case, setup then writes the agent’s tracing settings file (see Where settings live) and enables tracing. If you omit --project, setup uses your configured default project, or prompts you to pick one interactively. In non-interactive environments, pass --project <NAME> or set BRAINTRUST_DEFAULT_PROJECT, or setup fails with an explanatory error.

bt trace run

Use temporary tracing settings for one agent invocation without changing its saved setup:

bt trace run --project my-project opencode -- [OPENCODE_ARGS...]

Everything after the agent name is forwarded to the agent verbatim. The settings apply only to that invocation, and concurrent runs can each target a different project, organization, or profile. Command forms differ by agent. Use the examples in that agent’s guide.

bt trace import

Import a session that already happened. The agent’s own transcript on disk is the source, so this works even if tracing wasn’t set up when the session ran:

bt trace import claude <session-id>
bt trace import codex <session-id-1> <session-id-2>
bt trace import claude --all
bt trace import codex <session-id> --destination project_logs:<project-id>

Import supports claude and codex. The session ID is the one your agent shows in its resume or session list. Pass more than one session ID to import multiple sessions, or pass --all to import every locally discoverable session for that agent. The imported trace goes to your configured project by default. To send it somewhere specific, pass --destination with a reference such as project_logs:<project-id> or experiment:<experiment-id>, or use --parent <exported-span> to attach it below the span exported by span.export(). To follow a session that is still running, pass --attach with exactly one session ID. You cannot combine --attach with --all or multiple session IDs. Import keeps reading the transcript and sending new turns until you press Ctrl-C.

Import flags

Flag	Description
`--all`	Import every locally discoverable session for the agent
`--destination <DESTINATION>`	Destination object reference, such as `project_logs:<project-id>` or `experiment:<experiment-id>`
`--parent <SPAN_COMPONENTS>`	Attach the imported session below the span exported by `span.export()`
`--attach`	Keep following the transcript and import new turns as the session grows

Where settings live

bt trace setup writes tracing settings to the following global file for each agent:

Agent	File written by `bt trace setup`
Claude Code	`~/.claude/braintrust.json`
Codex	`~/.codex/braintrust.json`
OpenCode	`$XDG_CONFIG_HOME/opencode/braintrust.json` (defaults to `~/.config/opencode/braintrust.json`)
pi	`~/.pi/agent/braintrust.json`

OpenCode and pi can also read project settings from .opencode/braintrust.json and .pi/braintrust.json, respectively. bt trace setup does not create or update these project files.

What bt trace setup writes

Running bt trace setup <agent> --project <name> updates two top-level keys. On Unix-like systems, it sets the file permissions to 0600:

{
  "trace_to_braintrust": true,
  "route": {
    "auth": { "profile": "my-profile", "org_name": "my-org" },
    "destination": { "type": "project_logs", "project_name": "my-project" },
    "flush_mode": "fire_and_forget"
  }
}

Setup writes the project, profile, and organization selected for tracing. Pass --project, --profile, or --org to choose specific values. Otherwise, setup uses your active bt context or prompts you when necessary.

Settings reference

Setting	Settings file	Environment variable	Written by `bt trace setup`
Enable tracing	`trace_to_braintrust`	`TRACE_TO_BRAINTRUST`	Yes, set to `true`
Project	`route.destination`	`BRAINTRUST_PROJECT` (OpenCode and pi only)	Yes
`bt` profile	`route.auth.profile`	`BRAINTRUST_PROFILE`	Yes
Organization	`route.auth.org_name`	`BRAINTRUST_ORG_NAME`	Yes
Extra span metadata	`route.additional_metadata`	Agent-specific (Claude Code, Codex, OpenCode, pi)	No. Edit the settings file to save it
Credentials	Never stored here	See credential precedence	No

Credentials are the one thing the file never holds. Authentication happens through bt, exactly as it does for any other bt command, which also covers self-hosted deployments: the profile you log in with carries your deployment’s URLs, so traces go to the same data plane as the rest of your bt usage.

Precedence

Claude Code and Codex prefer their settings file over environment variables. For OpenCode and pi, project settings override global settings, and environment variables override both. bt trace run overrides these settings for a single invocation.

Troubleshooting

If the agent works normally but no traces appear, check the following, in order:

Is bt installed and current? Run bt --version. Tracing requires v0.16.0 or later.
Is bt logged in? Run bt status --verbose. It shows the active profile and authentication details. If nothing is logged in, run bt login.
Is tracing enabled for this agent? In the agent’s settings file, confirm that trace_to_braintrust is true and route.destination names the intended project.

Tracing failures do not stop the agent, so you can continue using it while you debug the setup.

Next steps

Follow the agent-specific guides for Claude Code, Codex, OpenCode, and pi.
Migrating from an earlier plugin or CLI version? See the CLI migration guide.
Learn what else the CLI can do in the CLI overview.

​bt trace setup

​bt trace run

​bt trace import

​Import flags

​Where settings live

​What bt trace setup writes

​Settings reference

​Precedence

​Troubleshooting

​Next steps