bt trace

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, and Cursor tracing requires v0.26.0 or later. Muse Code tracing requires bt v0.28.0 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, grok, cursor, or muse.
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, grok, cursor, or muse. 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.
Background tracing process: With bt v0.22.1 or later, asks the running background tracing process which credentials it resolves, and warns when it can’t authenticate or resolves different credentials than your shell.
Session errors: With bt v0.22.1 or later, shows the latest errors the background tracing process recorded for the agent’s sessions.
Delivery holds: With bt v0.27.2 or later, lists each session whose span updates are held, with the stage that holds them, the number of queued span operations, the retry attempts, and what bt is waiting for before it sends them.

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.
Cursor: Checks the installed plugin version and the hook entries in Cursor’s hooks.json.
Muse Code: Checks that Muse Code 1.3.0 or later is installed, that bt is on your PATH, and that the Braintrust hook entries in Muse Code’s settings.json are current.

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, grok, cursor, or muse. 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. 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, tags, and span plugins 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. With bt v0.24.0 or later, bt update also updates installed integrations. 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.
Cursor: ~/.cursor/braintrust.json.
Muse Code: $XDG_CONFIG_HOME/muse/braintrust.json (defaults to ~/.config/muse/braintrust.json).

On Unix-like systems, bt creates the config file with 0600 permissions. On Windows, bt v0.22.2 or later restricts it to the current user and SYSTEM.

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
Span plugins	`route.span_plugins`	`--plugin <PATH>` → 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, antigravity (v0.19.1 or later), cursor (v0.26.0 or later), and muse (v0.28.0 or later). 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. With v0.28.0 or later, Codex imports also read compressed .jsonl.zst transcripts. For Google Antigravity, use the conversation ID. For Cursor or Muse Code, use the session ID. Cursor imports include conversation text and the last turn’s status but not tool activity or token usage. bt reads Muse Code sessions with muse export, so muse must be on your PATH, or set BRAINTRUST_MUSE_BIN to its path. 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, or use it with a compressed Codex transcript. For Muse Code, pressing Ctrl-C stops following the session without ending it.
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
`--plugin <PATH>`	Apply a span plugin to the imported spans. Repeat for multiple plugins

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, pi, cursor (bt v0.26.0 or later), or muse (bt v0.28.0 or later). bt trace run does not support Antigravity or Grok. Use bt trace enable for persistent tracing instead. For Cursor, bt trace run launches the Cursor CLI (agent, or the executable in CURSOR_BIN) and requires an interactive terminal, so it rejects -p and --print. For Muse Code, bt trace run launches muse, or the executable in BRAINTRUST_MUSE_BIN, and requires Muse Code 1.3.0 or later.
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
Span plugins	`--plugin <PATH>` → 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, grok, cursor, or muse. 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.
Grok: Update the installed plugin from the published Braintrust source.
Cursor: Install the latest published plugin with Git, or the version bundled with bt if Git isn’t on your PATH, and refresh its hook entries in Cursor’s hooks.json.
Muse Code: Refresh the Braintrust hook entries in Muse Code’s settings.json. The command fails if the hooks aren’t installed.

For Claude Code and Codex, the command rejects local or custom marketplace sources. For Grok, it rejects local or custom plugin sources. For Cursor, it does not replace a plugin at the same path that is not Braintrust’s. Restart the agent after updating. For Grok, also run /reload-plugins in the session. For Cursor, reload the Cursor window. 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, from Cursor with v0.26.0 or later, and from Muse Code with v0.28.0 or later. 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.

Transform spans with JavaScript

With bt v0.21.0 or later, span plugins modify spans on your machine before they are sent to Braintrust, for example to redact secrets or add tags. Span plugins apply only to traces that bt sends.

To modify traces your application logs with a Braintrust SDK, use the SDK’s masking function or span customizers instead. See Protect sensitive data.

A span plugin is an ES module whose default export is a synchronous function that takes a span and a context object and returns the span to send:

redact-secrets.mjs

const SECRET_PATTERN = /\b(?:sk|pk|ghp)[-_][A-Za-z0-9_-]{16,}/g;

function redact(value) {
  if (typeof value === "string") {
    return value.replace(SECRET_PATTERN, "[REDACTED]");
  }
  if (Array.isArray(value)) {
    return value.map(redact);
  }
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value).map(([key, child]) => [key, redact(child)]),
    );
  }
  return value;
}

export default function redactSpan(span) {
  return {
    ...span,
    input: redact(span.input),
    output: redact(span.output),
    metadata: redact(span.metadata),
  };
}

bt trace enable claude --project <your-project> --plugin ./redact-secrets.mjs

This example redacts sk-, sk_, pk_, and ghp_ style keys. Adjust SECRET_PATTERN to match the credential formats you use. Repeat --plugin to chain plugins. They run in the order given.

Persistent tracing: bt trace enable saves plugin paths in route.span_plugins. Omitting --plugin keeps the saved list, and supplying it replaces the list.
One invocation: bt trace run and bt trace import use only the plugins passed to that command.

The span includes fields such as input, output, metadata, metrics, tags, and error. Plugins cannot change span_id, root_span_id, or parent_span_ids. The context includes operation ("insert" or "merge"), source, session_id, and env. Plugins run without filesystem or network access. With bt v0.27.2 or later, each plugin call must finish within 1 second, including converting the span to and from JavaScript. Earlier versions allow 50 milliseconds.

If a plugin fails, bt doesn’t send untransformed data. With bt v0.27.0 or later, traced sessions hold the affected span updates and send them after you change the plugin file or the configured plugin list. Restarting without changing the plugin doesn’t resend them. With bt v0.27.2 or later, when a plugin runs out of time, bt retries the affected span updates twice. If both retries time out, bt holds them until you change the plugin or upgrade bt. bt trace import drops the affected span updates and still reports them as imported. Run bt trace doctor to see plugin errors.

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, Grok tracing requires v0.19.3 or later, Cursor tracing requires v0.26.0 or later, and Muse Code tracing requires v0.28.0 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.The Claude Code, Codex, Cursor, Grok, and Google Antigravity plugins and the Muse Code hooks run bt by name, so bt must be on the PATH of the environment that launches the agent.To capture events with a different bt executable, such as one that a version manager selects only inside some directories, set BRAINTRUST_BT_BIN to its absolute path in the environment that launches the agent. With bt v0.27.2 or later, bt trace hook passes each event to that executable. The bt on PATH must also be v0.27.2 or later, because it’s the one that reads the variable. Point BRAINTRUST_BT_BIN at the executable itself, not a version-manager shim. If the path is relative, missing, or leads back through a shim, the hook fails with an error instead of falling back to the bt on PATH.

The agent reports a bt trace hook error

Agent plugins run bt trace hook for each event. Starting in v0.22.2, the command exits nonzero and writes the error to stderr when it can’t capture an event, such as when the tracing settings file is malformed, no destination is configured, or the background tracing process is unreachable. When trace_to_braintrust is false, the command exits successfully without capturing the event. Run bt trace doctor <coding-agent> to check the configuration.A successful exit means the background tracing process accepted the event, not that the trace reached Braintrust. Authentication and upload happen later, and bt trace doctor reports recent errors from those steps.

Spans appear late or are missing from a new destination

With bt v0.27.2 or later, the background tracing process sends spans in batches, after up to 30 seconds or 256 KiB of span data. It sends pending spans right away when a session ends, or at the end of each turn when route.flush_mode is flush_on_turn_end. Cursor, Google Antigravity, and Muse Code tracing always send pending spans at the end of each turn. For other agents in the default fire_and_forget mode, spans from a session that is still running can take up to 30 seconds to appear.If you change the tracing destination during a session, the new destination receives only spans that weren’t yet sent. To send the whole session to the new destination, use bt trace import.

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, Cursor, Grok, Muse Code, 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.

API

CLI

Terraform

SQL

bt trace disable

bt trace doctor

bt trace enable

bt trace import

bt trace run

bt trace update

Tag traces

Transform spans with JavaScript

Troubleshooting

Next steps

​bt trace disable

​bt trace doctor

​bt trace enable

​bt trace import

​bt trace run

​bt trace update

​Tag traces

​Transform spans with JavaScript

​Troubleshooting

​Next steps

bt trace disable

bt trace doctor

bt trace enable

bt trace import

bt trace run

bt trace update

Tag traces

Transform spans with JavaScript

Troubleshooting

Next steps