> ## 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 Claude Code, Codex, OpenCode, and pi sessions to Braintrust with one setup command, per-run tracing, and session imports.

`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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](/docs/integrations/developer-tools/claude-code), [Codex](/docs/integrations/developer-tools/codex), [OpenCode](/docs/integrations/developer-tools/opencode), and [pi](/docs/integrations/developer-tools/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](#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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "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](/docs/integrations/developer-tools/claude-code#settings), [Codex](/docs/integrations/developer-tools/codex#settings), [OpenCode](/docs/integrations/developer-tools/opencode#settings), [pi](/docs/integrations/developer-tools/pi#settings)) | No. Edit the settings file to save it |
| Credentials         | Never stored here           | See [credential precedence](/docs/reference/cli/overview#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](/docs/admin/self-hosting) 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:

1. **Is `bt` installed and current?** Run `bt --version`. Tracing requires v0.16.0 or later.
2. **Is `bt` logged in?** Run `bt status --verbose`. It shows the active profile and authentication details. If nothing is logged in, run `bt login`.
3. **Is tracing enabled for this agent?** In the agent's [settings file](#where-settings-live), 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](/docs/integrations/developer-tools/claude-code), [Codex](/docs/integrations/developer-tools/codex), [OpenCode](/docs/integrations/developer-tools/opencode), and [pi](/docs/integrations/developer-tools/pi).
* Migrating from an earlier plugin or CLI version? See the [CLI migration guide](/docs/reference/cli/migrate).
* Learn what else the CLI can do in the [CLI overview](/docs/reference/cli/overview).