bt trace - Braintrust

bt trace sends coding-agent activity to a Braintrust project, including sessions, conversation turns, model calls, and tool use. It supports Claude Code, Codex, OpenCode, and pi with bt v0.16.0 or later, and Google Antigravity with v0.19.1 or later. Grok tracing requires bt v0.19.3 or later. All bt trace subcommands accept the shared bt global flags. Tracing works through the agent’s hooks or native events:

Collection and delivery: The Braintrust integration observes events without sitting between the agent and its model provider. It sends those events to bt, which relays them to a background process that builds the trace and delivers it to Braintrust.
Authentication: The integration does not handle credentials. bt uses the same saved login or API key as other bt commands.
API endpoint: When a bt trace process sends traces, it resolves the selected organization’s data-plane API URL. An API URL supplied to that process with --api-url or BRAINTRUST_API_URL takes precedence.
Failure behavior: If any part of the tracing chain is missing or broken, the agent continues working normally, but traces are unavailable until the problem is fixed.

bt trace disable

Disable persistent tracing for an agent:

bt trace disable <coding-agent>

The command uses the specified agent as follows:

Coding agent: For <coding-agent>, specify claude, codex, opencode, pi, antigravity, or grok.
Agent integration: Uninstalls the agent’s Braintrust tracing plugin or integration.
Tracing settings: Deletes the agent-specific config file written by bt trace enable.
Credentials: Preserves saved bt login profiles and credentials.

Starting in bt v0.19.3, the command attempts to delete the tracing settings even if uninstalling the plugin fails. An uninstall error does not mean the tracing settings were preserved.

Flags bt trace disable has no command-specific flags.

bt trace doctor

Show the effective tracing configuration for a coding agent without changing it:

bt trace doctor <coding-agent>
bt trace doctor <coding-agent> --json

For <coding-agent>, specify claude, codex, opencode, pi, antigravity, or grok. The report includes the following details:

Authentication source: Identifies whether tracing uses an environment API key, a saved profile, or automatic resolution.
Profile details: Reports the profile name, organization, credential type, status, and OAuth expiration when available.
Credential safety: Never includes the credential value.

With bt v0.19.3 or later, bt trace doctor checks your tracing installation against the versions expected by your installed version of bt:

Claude Code and Codex: Checks the installed plugin version.
OpenCode and pi: Checks the package version requested in your configuration, not the exact version installed.

The command does not check online for newer releases. To confirm that tracing actually works, run a short agent session and check for its trace in Braintrust. Flags bt trace doctor has no command-specific flags. Pass the shared --json global flag to return the report as JSON.

bt trace enable

bt trace setup is a backward-compatible alias for bt trace enable.

Install or update a coding agent’s Braintrust integration, select a project, and enable tracing for future sessions:

bt trace enable <coding-agent> --project <your-project>

For <coding-agent>, specify claude, codex, opencode, pi, antigravity, or grok. For more information about a given tracing agent, see its linked guide. Starting in bt v0.19.3, this command selects v2 of the OpenCode and pi tracing integrations. For an existing v1 installation, follow the v0.19.3 migration instructions before rerunning setup.

bt trace enable antigravity requires macOS or Linux and a Unix-compatible sh. Grok’s tracing hooks require Bash.

Tracing configuration bt trace enable writes an agent-specific config file containing the tracing settings selected when the command runs. The trace_to_braintrust field controls whether tracing is enabled. The route object stores the tracing destination, authentication settings, additional metadata, tags, and trace-delivery settings. Later changes to the active bt context do not update the values stored in this file. Rerunning the command replaces the route object. Pass explicit profile, organization, and project options to preserve settings that differ from your active context. Existing additional metadata and tags are preserved unless overridden. Custom flush behavior resets to fire_and_forget. To update an installed integration without changing its saved tracing settings, use bt trace update. Complete any applicable configuration migrations in your agent’s guide first. The file location depends on the agent:

Claude Code: $CLAUDE_CONFIG_DIR/braintrust.json when CLAUDE_CONFIG_DIR is set, otherwise ~/.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.
Google Antigravity: ~/.gemini/config/braintrust.json.
Grok: ~/.grok/braintrust.json.

On Unix-like systems, bt creates the config file with 0600 permissions.

Flags The following table shows how bt trace enable sets each configuration value:

Setting	Configuration field	Inputs and fallback (higher → lower precedence)
Tracing state	`trace_to_braintrust`	Always `true`
Project	`route.destination`	`--project <your-project>` → `BRAINTRUST_DEFAULT_PROJECT` → active `bt` context → prompt
Credential source	`route.auth.source`	Always `saved_profile`
Profile	`route.auth.profile`, `route.auth.profile_id`	`--profile <NAME>` → `BRAINTRUST_PROFILE` → active `bt` context → prompt
Organization	`route.auth.org_name`	`--org <NAME>` → `BRAINTRUST_ORG_NAME` → active `bt` context → prompt
Root-span metadata	`route.additional_metadata`	`--additional-metadata <JSON>` → `BRAINTRUST_ADDITIONAL_METADATA` → previously saved value → unset
Root-span tags	`route.tags`	`--tag <TAG>` → `BRAINTRUST_TAGS` → previously saved value → none
Flush behavior	`route.flush_mode`	Always `fire_and_forget`

The config file stores the selected profile’s name and stable local ID in route.auth, but not the profile’s credential, which is managed by bt. In v0.19.0 or later, the stable ID remains unchanged when the profile is renamed, so tracing continues to use the same credentials. If no saved profile exists, bt trace enable creates one using BRAINTRUST_API_KEY or prompts for an API key before writing the profile reference to the config file.

Example config file

{
  "trace_to_braintrust": true,
  "route": {
    "auth": {
      "source": "saved_profile",
      "profile_id": "<profile-id>",
      "profile": "my-profile",
      "org_name": "my-org"
    },
    "destination": {
      "type": "project_logs",
      "project_name": "<your-project>"
    },
    "flush_mode": "fire_and_forget"
  }
}

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 <coding-agent> <session-id>
bt trace import <coding-agent> <session-id-1> <session-id-2>
bt trace import <coding-agent> --all
bt trace import <coding-agent> <session-id> --destination project_logs:<project-id>

Import supports claude, codex, and, with bt v0.19.1 or later, antigravity. It handles each import as follows:

Sessions: For Claude Code or Codex, use the session ID shown by the agent’s resume command or session list. For Google Antigravity, use the conversation ID. Pass multiple IDs to import multiple sessions, or pass --all to import every locally discoverable session for the agent.
Destination: Sends the imported trace to your configured project by default. To choose another destination or attach the trace below an existing span:
- Pass --destination with a reference such as project_logs:<project-id> or experiment:<experiment-id>.
- Pass --parent <exported-span> to attach it below the span exported by span.export().
- To identify a parent span directly, pass --parent-span-id with --parent-root-span-id and --parent-object-type. Also pass --parent-object-id, or pass --parent-project when the parent belongs to project logs.
Ongoing sessions: Pass --attach with exactly one session ID to continue importing new turns until you press Ctrl-C. You cannot combine --attach with --all or multiple session IDs.
Additional metadata: --additional-metadata <JSON> overrides BRAINTRUST_ADDITIONAL_METADATA. The resulting JSON object is merged into every imported root span’s metadata.

Flags The following flags control the import:

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_EXPORT>`	Attach the imported session below the span exported by `span.export()`
`--parent-span-id <SPAN_ID>`	Attach below a specific span ID. Also requires `--parent-root-span-id`, `--parent-object-type`, and either `--parent-object-id` or `--parent-project`
`--parent-root-span-id <ROOT_SPAN_ID>`	Root span ID used with `--parent-span-id`
`--parent-object-type <TYPE>`	Braintrust object type used with `--parent-span-id`: `experiment`, `project_logs`, or `playground_logs`
`--parent-object-id <OBJECT_ID>`	Braintrust object ID used with `--parent-span-id`
`--parent-project <PROJECT>`	Braintrust project name for a project-logs parent
`--attach`	Keep following the transcript and import new turns as the session grows
`--additional-metadata <JSON>`	Merge a JSON object into every imported root span’s metadata
`--tag <TAG>`	Tag imported session spans. Repeat for multiple tags or separate values with commas

bt trace run

With bt v0.19.3 or later, bt trace run pi loads v2 of the tracing extension.

Trace a single agent invocation without changing its persistent tracing configuration:

bt trace run \
  --project <your-project> \
  <coding-agent> \
  -- [AGENT_ARGS...]

Specify the agent and its arguments as follows:

Coding agent: For <coding-agent>, specify claude, codex, opencode, or pi. bt trace run does not support Antigravity or Grok. Use bt trace enable for persistent tracing instead.
Agent arguments: Arguments after -- are forwarded verbatim. The -- separator marks the end of the bt options and is not forwarded. Put tracing options such as --tag before this separator. For example, bt trace run --project <your-project> opencode -- run "summarize this repo" passes run "summarize this repo" to OpenCode. For Codex, bt rejects --dangerously-bypass-hook-trust because it conflicts with the hook managed by bt trace run.

Flags bt trace run resolves the tracing settings for each invocation from these inputs:

Setting	Inputs and fallback (higher → lower precedence)
Project	`--project <your-project>` → `BRAINTRUST_DEFAULT_PROJECT` → active `bt` context → prompt
Organization	`--org <NAME>` → `BRAINTRUST_ORG_NAME` → active `bt` context → prompt
Profile	`--profile <NAME>` → `BRAINTRUST_PROFILE` → active `bt` context → compatible saved profile → prompt
Root-span metadata	`--additional-metadata <JSON>` → `BRAINTRUST_ADDITIONAL_METADATA` → unset
Root-span tags	`--tag <TAG>` → `BRAINTRUST_TAGS` → none

BRAINTRUST_API_KEY overrides saved-profile credentials unless you pass --profile or --prefer-profile. The API key is used only for this invocation and is not saved to a profile. These settings apply only to that invocation and do not change the agent’s configuration file.

bt trace update

Update an installed tracing integration without changing its saved tracing configuration. Requires bt v0.19.3 or later:

bt trace update <coding-agent>

For <coding-agent>, specify claude, codex, opencode, pi, antigravity, or grok. The command preserves the saved tracing destination, authentication settings, metadata, tags, and trace-delivery settings. It does not configure or enable tracing. For a missing integration, follow its setup instructions in the linked guide.

Complete any applicable configuration migrations in your agent’s guide before updating. Updating a plugin does not migrate its tracing settings.

The update behavior depends on the agent:

Claude Code and Codex: Refresh the published Braintrust marketplace and update the installed tracing plugin.
OpenCode: Update the existing package entry in the global OpenCode configuration. OpenCode loads the configured package when it starts. The command does not download the package itself or change project-local registrations.
pi: Run pi’s updater for the installed Braintrust extension. To change an installation from v1 to v2, follow the pi migration instructions.
Google Antigravity: Update the installed tracing plugin through agy. Requires macOS or Linux.
Grok: Update the installed plugin from the published Braintrust source.

For Claude Code and Codex, the command rejects local or custom marketplace sources. For Grok, it rejects local or custom plugin sources. Restart the agent after updating. For Grok, also run /reload-plugins in the session. Flags bt trace update has no command-specific flags.

Tag traces

With bt v0.19.3 or later, you can add tags to session spans from Claude Code, Codex, Google Antigravity, OpenCode, and pi. Tags help you group and filter traces. Pass --tag once per tag, or separate tags with commas:

bt trace enable claude \
  --project <your-project> \
  --tag ci --tag release-validation

You can also set BRAINTRUST_TAGS=ci,release-validation when running bt trace enable, bt trace run, or bt trace import. Explicit --tag options take precedence over the environment variable. Leading and trailing whitespace is removed, duplicate tags are ignored, and empty tags are rejected.

Persistent tracing: bt trace enable saves tags in route.tags. Omitting both --tag and BRAINTRUST_TAGS preserves the saved tags. Supplying tags replaces the saved list.
One invocation: bt trace run and bt trace import apply tags only to that invocation. They do not inherit saved tags or change the tracing configuration.

To stop adding saved tags to new sessions, set route.tags to [] in the applicable tracing configuration. This does not remove tags from traces already logged.

Grok tracing does not emit configured tags in bt v0.19.3, even though the command accepts --tag.

Troubleshooting

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

The installed bt version does not support tracing

Run bt --version. Tracing requires v0.16.0 or later. Google Antigravity tracing requires v0.19.1 or later, and Grok tracing requires v0.19.3 or later. For an earlier version, follow the CLI migration guide.

bt is not authenticated

Run bt status --all to check saved profiles, selected context, and whether BRAINTRUST_API_KEY is overriding saved profiles. Refresh an expired OAuth profile with bt login --refresh --profile <name>. Run bt login --profile <name> only when no usable profile exists.

Your account cannot write project logs

Successful authentication does not guarantee permission to send traces. Writing traces requires Update permission on the selected project’s Logs, including when adding new traces.Check the profile and destination in bt trace doctor <coding-agent> to identify the account and project. Ask an administrator to grant this permission to the user or service account whose credentials tracing uses, either directly or through a permission group.After access is granted, submit a new prompt in the agent and check the project’s logs for a trace.

Tracing is not enabled for the agent

Run bt trace doctor <coding-agent>. In the agent’s settings file, confirm that trace_to_braintrust is true and route.destination names the intended project.

The agent integration is missing or broken

If tracing settings and authentication are valid but no traces appear, use the agent’s linked guide to check plugin installation, hook activation, and runtime settings. bt trace doctor does not verify that the agent loaded the plugin.

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

Next steps

Configure and troubleshoot the published integration for Claude Code, Codex, Google Antigravity, Grok, OpenCode, or pi.
Upgrade an earlier bt version with the CLI migration guide.
Follow the migration or update instructions in your agent’s guide to update its plugin or extension.
Learn what else the CLI can do in the CLI overview.

​bt trace disable

​bt trace doctor

​bt trace enable

​bt trace import

​bt trace run

​bt trace update

​Tag traces

​Troubleshooting

​Next steps

bt trace disable

bt trace doctor

bt trace enable

bt trace import

bt trace run

bt trace update

Tag traces

Troubleshooting

Next steps