> ## 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.

# Claude Code

> Trace Claude Code sessions to Braintrust and access your Braintrust data through the MCP server

[Claude Code](https://code.claude.com/docs/en/overview) is Anthropic's agentic coding tool, available from the terminal and from the Code tab in the Claude desktop app. You can connect it to Braintrust in three ways:

* **Trace Claude Code sessions** to record session, turn, model call, tool, and subagent spans in Braintrust.
* **Trace with OpenTelemetry** to send Claude Code's native OpenTelemetry export to Braintrust without the tracing plugin.
* **Connect to Braintrust MCP** to work with Braintrust projects, experiments, logs, and other data from Claude Code.

> [!NOTE]
>
> This guide covers the Claude Code CLI and local Claude Code sessions in the Code tab of the desktop app. Both interfaces use the same tracing plugin and native Claude Code MCP configuration.

## Trace Claude Code sessions

The [`trace-claude-code` plugin](https://github.com/braintrustdata/braintrust-claude-plugin) uses `bt` to trace your Claude Code sessions to Braintrust.

If you can't install Claude Code plugins, or you want to route Claude Code telemetry through an existing OpenTelemetry pipeline, [trace with OpenTelemetry](#trace-with-opentelemetry) instead.

### Set up tracing

> [!NOTE]
>
> If `trace-claude-code` is already installed, follow [Update the tracing plugin](#update-the-tracing-plugin).

**1. Install Claude Code**

If you haven't already, install the [Claude Code CLI](https://code.claude.com/docs/en/overview) or the [Claude Code desktop app](https://code.claude.com/docs/en/desktop-quickstart).

**2. Install and authenticate bt**

Follow the [`bt` CLI quickstart](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt`, authenticate, and set your active context.

**3. Enable tracing**

Before starting Claude Code, run this command in a terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable claude --project <your-project>
```

This command:

* Adds or refreshes the Braintrust [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces).
* Installs (or updates) and enables [`trace-claude-code`](https://github.com/braintrustdata/braintrust-claude-plugin).
* Writes a Claude-specific tracing config file, normally `~/.claude/braintrust.json`, which records whether tracing is enabled and which project receives traces.

The tracing file stores settings, not credentials. These settings apply across projects during normal sessions.

For more information, see [`bt trace enable`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable).

**4. Restart Claude Code**

Exit any running Claude Code CLI or desktop sessions and start a new local session.

**5. Log a test trace**

Ask Claude Code to do something simple in the terminal or the Code tab in the Claude desktop app. When the session finishes, open your Braintrust project and confirm that the trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page.

### What Braintrust traces

Claude Code traces in Braintrust include:

* Session spans with the session ID, workspace, hostname, username, operating system, Claude Code version, model, system prompt when available, Git repository metadata, the final response of the last completed turn, and the session's status in `metadata.session_status` when the session ends.
* Turn spans with prompts, final responses, the permission mode, the effort level, and how the turn ended in `metadata.outcome` (`completed`, `interrupted`, or `errored`). Interrupted turns aren't recorded as errors.
* Model call spans with prompts, completions, token metrics, and errors.
* Tool spans with inputs, outputs, approval state, and tool names. `AskUserQuestion` calls are task spans with `metadata.wait_kind` set to `user_question`, so time spent waiting for your answer isn't counted as tool time.
* Skill metadata when a turn loads skills.
* Subagent spans nested under the turn that started the subagent, with the report the subagent handed back, or its final response, as output.
* Compaction spans when Claude Code compacts the conversation.

Every span records its origin as `braintrust.plugin.claude-code`, along with versions in `context.span_origin`: the plugin version in `version`, the `bt` version in `bt.version`, and the Claude Code version in `claude-code.version`. These versions are captured when each span is created, and unknown versions are `null`. Each turn span and every span under it, including subagent spans, records the turn's span ID in `metadata.turn_span_id`. The session span also records the plugin version in `trace_claude_code_version`.

### Common workflows

> [accordion] Use different tracing settings for one session
>
> Use [`bt trace run`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-run) to trace a single Claude Code invocation without changing the saved tracing configuration.
>
> This workflow launches Claude Code from the terminal.
>
> To change the saved destination, profile, or organization, rerun [`bt trace enable claude`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/reference/cli/switch) does not change the saved tracing configuration.
>
> To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace run` for one invocation or to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.
>
> With `bt` v0.19.3 or later, pass `--tag ci --tag release-validation` to either command to [tag session spans](https://docs.braintrust.dev/reference/cli/trace.md#tag-traces).

> [accordion] Trace a saved Claude Code session
>
> Claude Code stores session transcripts locally. Use [`bt trace import`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-import) to import a past session, even if tracing was not enabled when it ran.
>
> You can also attach an imported session to an existing span or experiment.

> [accordion] Resume a Claude Code session
>
> When you [resume a Claude Code session](https://code.claude.com/docs/en/cli-reference) that hasn't ended, new turns are added to its existing Braintrust trace. With `bt` v0.27.0 or later, resuming a session that already ended, for example after you exit Claude Code, starts a new trace with the same `session_id`.

> [accordion] Stop tracing Claude Code sessions
>
> Use [`bt trace disable claude`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-disable) to uninstall the tracing plugin and remove its tracing configuration. Saved `bt` profiles and credentials are preserved. Restart Claude Code afterward.

### Update the tracing plugin

To update the plugin, follow these steps:

> [!NOTE]
>
> If `claude plugin list --json` shows `trace-claude-code` earlier than v2.0.1, or `bt --version` shows a version earlier than v0.19.0, follow [Migrate from an older plugin version](#migrate-from-an-older-plugin-version).

**1. Update bt**

Follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations.

**2. Update the tracing plugin**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update claude
```

[`bt trace update`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-update) updates the installed plugin without changing your saved tracing configuration.

**3. Restart and verify Claude Code**

Restart Claude Code, run a short local session in the CLI or desktop app, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

### Migrate from an older plugin version

To migrate to the latest version of the `trace-claude-code` plugin, follow these steps:

**1. Inspect your Claude plugins**

Run this command and find `trace-claude-code@braintrust-claude-plugin`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
claude plugin list --json
```

Record the tracing plugin's starting `version` before updating. If your tracing configuration file exists, also record its profile, organization, project, and any custom tracing settings you want to preserve.

> [!NOTE]
>
> If the tracing plugin is not installed, follow [Set up tracing](#set-up-tracing).

**2. Install or update bt**

Check whether `bt` is installed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt --version
```

* If the command succeeds, [migrate to the latest version](https://docs.braintrust.dev/reference/cli/migrate.md) (unless you've already done so).
* Otherwise, [install `bt`](https://docs.braintrust.dev/reference/cli/quickstart), authenticate, and set organization and project context.

**3. Complete version-specific migration steps**

> [!NOTE]
>
> Complete each section for a version newer than your starting `trace-claude-code` version, beginning with the oldest. If no sections apply, continue to the next step.

> [accordion] trace-claude-code v2.0.1
>
> > [!NOTE]
> >
> > Complete this section if you started your migration from a tracing-plugin version earlier than v2.0.1.
>
> Before v2.0.1, the tracing plugin read settings from Claude's environment. Starting in v2.0.1, it reads a dedicated configuration file written by `bt trace enable claude`.
>
> If you don't know which Braintrust project has been receiving your traces, find the value of the `BRAINTRUST_CC_PROJECT` variable.
>
> To find it, look in the `env` object in `~/.claude/settings.json` or the project's `.claude/settings.local.json`, and in your shell configuration. If it is not set, the earlier plugin used the `claude-code` project.

**4. Apply your tracing settings**

Run this command with your intended project, using the project you recorded earlier to preserve your destination:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable claude --project <your-project>
```

Pass `--profile <profile>` and `--org <organization>` if needed to preserve your tracing account and organization. Otherwise, the command uses your active `bt` context, not your saved tracing settings.

To preserve metadata from an older plugin's configuration or `BRAINTRUST_ADDITIONAL_METADATA`, pass it explicitly with `--additional-metadata '<JSON>'`. Normal-session hooks do not read metadata from this environment variable.

The command updates your tracing file, normally `~/.claude/braintrust.json`. Check the following settings in that file:

* Existing `route.additional_metadata` is preserved unless you pass `--additional-metadata`.
* Existing `route.tags` is preserved unless you pass `--tag` or set `BRAINTRUST_TAGS`.
* `route.flush_mode` resets to `fire_and_forget`. Restore its previous value if you customized it.
* Restore any other custom tracing settings you recorded before updating.

**5. Restart and verify Claude Code**

Restart Claude Code, run a short local session in the CLI or desktop app, and confirm that its trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

**6. Remove obsolete environment settings**

> [!NOTE]
>
> Complete this step only if you started with a tracing-plugin version earlier than v2.0.1 and verified that traces reach the intended project in the previous step.

> [accordion] Environment settings used before trace-claude-code v2.0.1
>
> The tracing plugin now reads its settings from a dedicated configuration file. Environment variables you previously configured for tracing may no longer be needed.
>
> Check these locations for leftover settings:
>
> * The `env` object in `~/.claude/settings.json`
> * The `env` object in your project's `.claude/settings.local.json`
> * Your shell configuration
>
> Remove the variables below if they were used only for tracing. Keep any that other `bt` commands, MCP connections, or integrations still need:
>
> * `TRACE_TO_BRAINTRUST`
> * `BRAINTRUST_CC_PROJECT`
> * `BRAINTRUST_API_KEY`
> * `BRAINTRUST_API_URL` and `BRAINTRUST_APP_URL`
> * `BRAINTRUST_ORG_NAME`
> * `CC_PARENT_SPAN_ID`, `CC_ROOT_SPAN_ID`, and `CC_EXPERIMENT_ID`
> * `BRAINTRUST_CC_DEBUG`, `BRAINTRUST_ENVIRONMENT_TYPE`, and `BRAINTRUST_ENVIRONMENT_NAME`

### Troubleshooting tracing

First, run `bt trace doctor claude`. Then, review the following:

> [accordion] The tracing plugin is missing or disabled
>
> Run `claude plugin list` and confirm that `trace-claude-code@braintrust-claude-plugin` is installed and enabled. If it is missing or broken, run:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace enable claude --project <your-project>
> ```
>
> Restart Claude Code afterward.

> [accordion] Traces do not appear after setup
>
> Opening Claude Code alone does not create a trace. Submit a prompt to verify tracing.
>
> If Claude Code was running when its plugin or configuration changed, restart it.
>
> Confirm that `bt` is on the `PATH` of the environment that launches Claude Code.
>
> Run `bt trace doctor claude` and confirm that tracing is enabled and routed to the intended project.
>
> If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](https://docs.braintrust.dev/reference/cli/migrate.md#troubleshooting).
>
> Tracing failures do not interrupt the Claude Code session.

> [accordion] Claude Code uses an unexpected configuration directory
>
> Check whether [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) is set in the environment that launches Claude Code. When it's set, `bt trace enable claude` and the tracing integration use `$CLAUDE_CONFIG_DIR/braintrust.json` instead of `~/.claude/braintrust.json`.
>
> An explicit `BRAINTRUST_DAEMON_CONFIG` (`BT_DAEMON_CONFIG` in `bt` v0.25.0 and earlier) override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Claude Code.

> [accordion] Traces use unexpected settings
>
> Invocation settings supplied by `bt trace run` take precedence over the saved tracing configuration. For normal sessions, the integration does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_CC_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.
>
> For environment variables accepted by the `bt` commands themselves, see [`bt trace`](https://docs.braintrust.dev/reference/cli/trace).

> [accordion] bt reports obsolete tracing environment settings
>
> `bt trace enable claude` warns when Claude settings contain environment variables used by an earlier tracing plugin.
>
> > [!NOTE]
> >
> > Follow step 6, "Remove obsolete environment settings," under [Migrate from an older plugin version](#migrate-from-an-older-plugin-version) to clean up these variables.

## Trace with OpenTelemetry

Claude Code can [export OpenTelemetry traces and events](https://code.claude.com/docs/en/monitoring-usage) directly to Braintrust's OTLP endpoint, without the tracing plugin or `bt`.

### Set up tracing

**1. Configure the OTLP exporter**

Set these environment variables before starting Claude Code:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.braintrust.dev/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <BRAINTRUST_API_KEY>,x-bt-parent=project_id:<PROJECT_ID>"
```

The `x-bt-parent` header sets the Braintrust project that receives the traces. It also accepts `project_name:<PROJECT_NAME>`. Organizations on the EU data plane use `https://api-eu.braintrust.dev/otel`, and self-hosted deployments use their data plane's API URL followed by `/otel`.

**2. Capture prompts and tool content (optional)**

By default, Claude Code redacts prompts and omits tool details. To include them in traces, also set:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1
```

> [!WARNING]
>
> These options send prompts, commands, file paths, and tool output to Braintrust. Review your organization's data handling policies before enabling them.

**3. Export Claude Code events (optional)**

To also send Claude Code events, such as API requests, errors, and tool results, as [log records](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/attributes.md#log-records), set:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export OTEL_LOGS_EXPORTER=otlp
```

**4. Start Claude Code**

Start Claude Code and submit a prompt. Confirm that the trace appears on the [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs) page of the project you set in `x-bt-parent`.

### What Braintrust traces

Braintrust maps Claude Code spans to typed spans:

| Claude Code span | Braintrust span |
| - | - |
| `claude_code.interaction` | Task span. The user prompt becomes the input when `OTEL_LOG_USER_PROMPTS=1`. |
| `claude_code.llm_request` | LLM span with the model, token metrics, and time to first token, so Braintrust can estimate cost. Cache read and cache creation tokens are included in prompt tokens. |
| `claude_code.tool` | Tool span named after the tool, such as `Bash` or `Read`. Tool input requires `OTEL_LOG_TOOL_DETAILS=1`, and tool output requires `OTEL_LOG_TOOL_CONTENT=1`. |
| `claude_code.hook` | Task span named after the hook, such as `PreToolUse:Read`. |
| Other spans, such as `claude_code.tool.execution` | Task span. |

With Claude Code's [detailed beta tracing](https://code.claude.com/docs/en/monitoring-usage) active, LLM spans also show the conversation as input messages and the model response as output. Values that Claude Code redacts as `<REDACTED>` are never used as input or output.

When you export events, each event becomes a log row. Braintrust sets the prompt as input, the assistant response as output, and populates `error` for API errors, failed tool results, and internal errors. API request events carry token metrics only when they have no trace ID, so tokens aren't counted twice when you export both traces and events.

## Connect to Braintrust MCP

The Braintrust MCP server lets Claude Code query and update Braintrust data. MCP is configured independently from the tracing plugin.

> [accordion] Remove the retired Braintrust MCP plugin (if installed)
>
> Braintrust retired its `braintrust` MCP plugin for Claude Code in favor of Claude Code's native MCP configuration. If you installed the plugin, remove it before configuring the direct connection.
>
> Check whether the plugin is still installed:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> claude plugin list --json
> ```
>
> If `braintrust@braintrust-claude-plugin` appears in the list, use its `scope` value to remove it:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> claude plugin uninstall braintrust@braintrust-claude-plugin \
>   --scope <scope>
> ```
>
> If it appears at more than one scope, repeat the command for each scope. Keep the marketplace if you use the `trace-claude-code` tracing plugin.

**1. Choose authentication**

> [tab] OAuth (recommended)
>
> Use OAuth when your client supports it. Your client opens a Braintrust authorization page where you sign in and approve access. The server acts with the permissions of the account you sign in with.
>
> * No Braintrust API key required
> * No OAuth client ID or client secret to configure
>
> The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at `/.well-known/oauth-authorization-server` on the same host as your MCP endpoint (see next step), so a client can register itself.

> [tab] API key
>
> Use an API key for clients without OAuth support or for programmatic connections. The server acts with the permissions of the account the key belongs to.
>
> 1. Create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
> 2. Configure your client to send this header on every request, replacing `YOUR_BRAINTRUST_API_KEY` with your key:
>
>    ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
>    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
>    ```

> [!NOTE]
>
> Your [`bt login`](https://docs.braintrust.dev/reference/cli/login) doesn't authenticate the MCP server.

**2. Choose your endpoint**

Use the endpoint for your organization's [data plane region](https://docs.braintrust.dev/admin/organizations.md#data-plane-region):

| Region | MCP endpoint |
| - | - |
| US | `https://api.braintrust.dev/mcp` |
| EU | `https://api-eu.braintrust.dev/mcp` |

Other connection details:

* **Self-hosted:** Copy the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/data-plane). This is your Braintrust API URL with `/mcp` appended.
* **Transport:** If your client asks you to choose a transport, choose HTTP (also called streamable HTTP). SSE-only clients can't connect.

**3. Add the server to Claude Code**

Follow the [Claude Code guide](https://code.claude.com/docs/en/mcp) to add the remote server.

**4. Verify the connection**

To verify the connection, ask Claude Code to list your recent Braintrust projects. If it can't connect, see [Braintrust MCP troubleshooting](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#troubleshooting).

**5. Start using Braintrust tools**

Claude Code can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:

* "Show me my recent Braintrust experiments."
* "Query the last 10 logged requests with errors."
* "Compare accuracy scores between my two latest experiments."

See [what the Braintrust MCP can do](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](https://docs.braintrust.dev/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](https://docs.braintrust.dev/evaluate/run-evaluations.md).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.