> ## 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. # bt trace > Trace coding-agent sessions to Braintrust with persistent tracing, per-run tracing, and session imports. `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](/docs/integrations/developer-tools/antigravity) with v0.19.1 or later. [Grok](/docs/integrations/developer-tools/grok) tracing requires `bt` v0.19.3 or later. All `bt trace` subcommands accept the shared [`bt` global flags](/docs/reference/cli/overview#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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace disable ``` The command uses the specified agent as follows: * **Coding agent:** For ``, specify [`claude`](/docs/integrations/developer-tools/claude-code), [`codex`](/docs/integrations/developer-tools/codex), [`opencode`](/docs/integrations/developer-tools/opencode), [`pi`](/docs/integrations/developer-tools/pi), [`antigravity`](/docs/integrations/developer-tools/antigravity), or [`grok`](/docs/integrations/developer-tools/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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace doctor bt trace doctor --json ``` For ``, specify [`claude`](/docs/integrations/developer-tools/claude-code), [`codex`](/docs/integrations/developer-tools/codex), [`opencode`](/docs/integrations/developer-tools/opencode), [`pi`](/docs/integrations/developer-tools/pi), [`antigravity`](/docs/integrations/developer-tools/antigravity), or [`grok`](/docs/integrations/developer-tools/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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace enable --project ``` For ``, specify [`claude`](/docs/integrations/developer-tools/claude-code), [`codex`](/docs/integrations/developer-tools/codex), [`opencode`](/docs/integrations/developer-tools/opencode), [`pi`](/docs/integrations/developer-tools/pi), [`antigravity`](/docs/integrations/developer-tools/antigravity), or [`grok`](/docs/integrations/developer-tools/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](/docs/reference/cli/migrate#v0-19-3) 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`](#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 ` → `BRAINTRUST_DEFAULT_PROJECT` → active `bt` context → prompt | | Credential source | `route.auth.source` | Always `saved_profile` | | Profile | `route.auth.profile`, `route.auth.profile_id` | `--profile ` → `BRAINTRUST_PROFILE` → active `bt` context → prompt | | Organization | `route.auth.org_name` | `--org ` → `BRAINTRUST_ORG_NAME` → active `bt` context → prompt | | Root-span metadata | `route.additional_metadata` | `--additional-metadata ` → `BRAINTRUST_ADDITIONAL_METADATA` → previously saved value → unset | | [Root-span tags](#tag-traces) | `route.tags` | `--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. ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} { "trace_to_braintrust": true, "route": { "auth": { "source": "saved_profile", "profile_id": "", "profile": "my-profile", "org_name": "my-org" }, "destination": { "type": "project_logs", "project_name": "" }, "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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace import bt trace import bt trace import --all bt trace import --destination project_logs: ``` 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:` or `experiment:`. * Pass `--parent ` 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 ` 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 object reference, such as `project_logs:` or `experiment:` | | `--parent ` | Attach the imported session below the span exported by `span.export()` | | `--parent-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 used with `--parent-span-id` | | `--parent-object-type ` | Braintrust object type used with `--parent-span-id`: `experiment`, `project_logs`, or `playground_logs` | | `--parent-object-id ` | Braintrust object ID used with `--parent-span-id` | | `--parent-project ` | Braintrust project name for a project-logs parent | | `--attach` | Keep following the transcript and import new turns as the session grows | | `--additional-metadata ` | Merge a JSON object into every imported root span's metadata | | `--tag ` | [Tag imported session spans](#tag-traces). 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace run \ --project \ \ -- [AGENT_ARGS...] ``` Specify the agent and its arguments as follows: * **Coding agent:** For ``, specify [`claude`](/docs/integrations/developer-tools/claude-code), [`codex`](/docs/integrations/developer-tools/codex), [`opencode`](/docs/integrations/developer-tools/opencode), or [`pi`](/docs/integrations/developer-tools/pi). `bt trace run` does not support Antigravity or Grok. Use [`bt trace enable`](#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 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 ` → `BRAINTRUST_DEFAULT_PROJECT` → active `bt` context → prompt | | Organization | `--org ` → `BRAINTRUST_ORG_NAME` → active `bt` context → prompt | | Profile | `--profile ` → `BRAINTRUST_PROFILE` → active `bt` context → compatible saved profile → prompt | | Root-span metadata | `--additional-metadata ` → `BRAINTRUST_ADDITIONAL_METADATA` → unset | | [Root-span tags](#tag-traces) | `--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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace update ``` For ``, specify [`claude`](/docs/integrations/developer-tools/claude-code), [`codex`](/docs/integrations/developer-tools/codex), [`opencode`](/docs/integrations/developer-tools/opencode), [`pi`](/docs/integrations/developer-tools/pi), [`antigravity`](/docs/integrations/developer-tools/antigravity), or [`grok`](/docs/integrations/developer-tools/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](/docs/integrations/developer-tools/pi#migrate-from-an-older-extension-version). * **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](/docs/annotate/labels#apply-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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace enable claude \ --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](#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: 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](/docs/reference/cli/migrate). 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 `. Run `bt login --profile ` only when no usable profile exists. 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 ` to identify the account and project. Ask an administrator to [grant this permission](/docs/admin/access-control/manage-permissions#set-project-permissions) 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. Run `bt trace doctor `. In the agent's [settings file](#tracing-configuration), confirm that `trace_to_braintrust` is `true` and `route.destination` names the intended project. 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](/docs/integrations/developer-tools/claude-code), [Codex](/docs/integrations/developer-tools/codex), [Google Antigravity](/docs/integrations/developer-tools/antigravity), [Grok](/docs/integrations/developer-tools/grok), [OpenCode](/docs/integrations/developer-tools/opencode), or [pi](/docs/integrations/developer-tools/pi). * Upgrade an earlier `bt` version with the [CLI migration guide](/docs/reference/cli/migrate). * 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](/docs/reference/cli/overview).