> ## Documentation Index > Fetch the complete documentation index at: https://docs.braintrust.dev/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](https://docs.braintrust.dev/integrations/developer-tools/antigravity.md) with v0.19.1 or later. [Grok](https://docs.braintrust.dev/integrations/developer-tools/grok.md) tracing requires `bt` v0.19.3 or later, and [Cursor](https://docs.braintrust.dev/integrations/developer-tools/cursor.md) tracing requires v0.26.0 or later. [Muse Code](https://docs.braintrust.dev/integrations/developer-tools/muse-code.md) tracing requires `bt` v0.28.0 or later. All `bt trace` subcommands accept the shared [`bt` global flags](https://docs.braintrust.dev/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`](https://docs.braintrust.dev/integrations/developer-tools/claude-code), [`codex`](https://docs.braintrust.dev/integrations/developer-tools/codex), [`opencode`](https://docs.braintrust.dev/integrations/developer-tools/opencode), [`pi`](https://docs.braintrust.dev/integrations/developer-tools/pi), [`antigravity`](https://docs.braintrust.dev/integrations/developer-tools/antigravity), [`grok`](https://docs.braintrust.dev/integrations/developer-tools/grok), [`cursor`](https://docs.braintrust.dev/integrations/developer-tools/cursor), or [`muse`](https://docs.braintrust.dev/integrations/developer-tools/muse-code). * **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. > [!WARNING] > > 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`](https://docs.braintrust.dev/integrations/developer-tools/claude-code), [`codex`](https://docs.braintrust.dev/integrations/developer-tools/codex), [`opencode`](https://docs.braintrust.dev/integrations/developer-tools/opencode), [`pi`](https://docs.braintrust.dev/integrations/developer-tools/pi), [`antigravity`](https://docs.braintrust.dev/integrations/developer-tools/antigravity), [`grok`](https://docs.braintrust.dev/integrations/developer-tools/grok), [`cursor`](https://docs.braintrust.dev/integrations/developer-tools/cursor), or [`muse`](https://docs.braintrust.dev/integrations/developer-tools/muse-code). 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 > [!TIP] > > `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`](https://docs.braintrust.dev/integrations/developer-tools/claude-code), [`codex`](https://docs.braintrust.dev/integrations/developer-tools/codex), [`opencode`](https://docs.braintrust.dev/integrations/developer-tools/opencode), [`pi`](https://docs.braintrust.dev/integrations/developer-tools/pi), [`antigravity`](https://docs.braintrust.dev/integrations/developer-tools/antigravity), [`grok`](https://docs.braintrust.dev/integrations/developer-tools/grok), [`cursor`](https://docs.braintrust.dev/integrations/developer-tools/cursor), or [`muse`](https://docs.braintrust.dev/integrations/developer-tools/muse-code). 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](https://docs.braintrust.dev/reference/cli/migrate.md#v0-19-3) 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`](#bt-trace-update). With `bt` v0.24.0 or later, [`bt update`](https://docs.braintrust.dev/reference/cli/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`). > [!NOTE] > > 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 ` → `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 | | [Span plugins](#transform-spans-with-javascript) | `route.span_plugins` | `--plugin ` → 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. > [accordion] Example 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`, `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:` 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, 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 ` 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 | | `--plugin ` | Apply a [span plugin](#transform-spans-with-javascript) to the imported spans. Repeat for multiple plugins | ## bt trace run > [!NOTE] > > 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`](https://docs.braintrust.dev/integrations/developer-tools/claude-code), [`codex`](https://docs.braintrust.dev/integrations/developer-tools/codex), [`opencode`](https://docs.braintrust.dev/integrations/developer-tools/opencode), [`pi`](https://docs.braintrust.dev/integrations/developer-tools/pi), [`cursor`](https://docs.braintrust.dev/integrations/developer-tools/cursor) (`bt` v0.26.0 or later), or [`muse`](https://docs.braintrust.dev/integrations/developer-tools/muse-code) (`bt` v0.28.0 or later). `bt trace run` does not support Antigravity or Grok. Use [`bt trace enable`](#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 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 | | [Span plugins](#transform-spans-with-javascript) | `--plugin ` → 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`](https://docs.braintrust.dev/integrations/developer-tools/claude-code), [`codex`](https://docs.braintrust.dev/integrations/developer-tools/codex), [`opencode`](https://docs.braintrust.dev/integrations/developer-tools/opencode), [`pi`](https://docs.braintrust.dev/integrations/developer-tools/pi), [`antigravity`](https://docs.braintrust.dev/integrations/developer-tools/antigravity), [`grok`](https://docs.braintrust.dev/integrations/developer-tools/grok), [`cursor`](https://docs.braintrust.dev/integrations/developer-tools/cursor), or [`muse`](https://docs.braintrust.dev/integrations/developer-tools/muse-code). 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. > [!NOTE] > > 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](https://docs.braintrust.dev/integrations/developer-tools/pi.md#migrate-from-an-older-extension-version). * **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](https://docs.braintrust.dev/annotate/labels.md#apply-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: ```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. > [!NOTE] > > 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. > [!TIP] > > To modify traces your application logs with a Braintrust SDK, use the SDK's masking function or span customizers instead. See [Protect sensitive data](https://docs.braintrust.dev/admin/data-management/protect-sensitive-data.md#redact-before-upload). 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: ```js redact-secrets.mjs theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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), }; } ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt trace enable claude --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. > [!WARNING] > > 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`](#bt-trace-doctor) to see plugin errors. ## Troubleshooting If the agent works normally but no traces appear, check these issues in order: > [accordion] 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](https://docs.braintrust.dev/reference/cli/migrate.md). > [accordion] 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 `. Run `bt login --profile ` only when no usable profile exists. > [accordion] 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 ` to identify the account and project. Ask an administrator to [grant this permission](https://docs.braintrust.dev/admin/access-control/manage-permissions.md#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. > [accordion] Tracing is not enabled for the agent > > 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. > [accordion] 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`. > [accordion] 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 ` 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. > [accordion] 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`](#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](https://docs.braintrust.dev/integrations/developer-tools/claude-code.md), [Codex](https://docs.braintrust.dev/integrations/developer-tools/codex.md), [Google Antigravity](https://docs.braintrust.dev/integrations/developer-tools/antigravity.md), [Cursor](https://docs.braintrust.dev/integrations/developer-tools/cursor.md), [Grok](https://docs.braintrust.dev/integrations/developer-tools/grok.md), [Muse Code](https://docs.braintrust.dev/integrations/developer-tools/muse-code.md), [OpenCode](https://docs.braintrust.dev/integrations/developer-tools/opencode.md), or [pi](https://docs.braintrust.dev/integrations/developer-tools/pi.md). * Upgrade an earlier `bt` version with the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md). * 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](https://docs.braintrust.dev/reference/cli/overview.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.