Skip to main content
Claude Code 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 two ways:
  • Trace Claude Code sessions to record session, turn, model call, tool, and subagent spans in Braintrust.
  • Connect to Braintrust MCP to work with Braintrust projects, experiments, logs, and other data from Claude Code.
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 passes your interactions with Claude Code to bt, which in turn uses a background process to build and deliver the trace to Braintrust. Claude Code continues to communicate directly with its model provider, and tracing failures do not stop your Claude Code session.

​
Set up tracing

If trace-claude-code is already installed, follow Update the tracing plugin.
1

Install Claude Code

If you haven’t already, install the Claude Code CLI or the Claude Code desktop app.
2

Install and authenticate bt

Follow the bt CLI quickstart to install bt, authenticate, and set your active context.
3

Enable tracing

Before starting Claude Code, run this command in a terminal:
This command:
  • Adds or refreshes the Braintrust plugin marketplace.
  • Installs (or updates) and enables trace-claude-code.
  • 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.
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 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, and Git repository metadata.
  • Turn spans with prompts and final responses.
  • Model call spans with prompts, completions, token metrics, and errors.
  • Tool spans with inputs, outputs, approval state, and tool names.
  • Skill metadata when a turn loads skills.
  • Subagent spans nested under the turn that started the subagent.
Every span records its origin as braintrust.plugin.claude-code, and the session span records the plugin version in trace_claude_code_version.

​
Common workflows

Use 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 with the corresponding options. Running bt 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.
Claude Code stores session transcripts locally. Use 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.
When you resume a Claude Code session, new turns are added to its existing Braintrust trace.
Use bt trace disable claude 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:
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.
1

Update bt

Follow the CLI migration guide to update bt to the latest version and complete the applicable migrations.
2

Update the tracing plugin

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 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:
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.
If the tracing plugin is not installed, follow Set up tracing.
2

Install or update bt

Check whether bt is installed:
3

Complete version-specific migration steps

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.
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:
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 page in the intended Braintrust project.
6

Remove obsolete environment settings

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.
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:
Run claude plugin list and confirm that trace-claude-code@braintrust-claude-plugin is installed and enabled. If it is missing or broken, run:
Restart Claude Code afterward.
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.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.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting and the CLI migration troubleshooting guide.Tracing failures do not interrupt the Claude Code session.
Check whether CLAUDE_CONFIG_DIR 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 BT_DAEMON_CONFIG override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Claude Code.
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.
bt trace enable claude warns when Claude settings contain environment variables used by an earlier tracing plugin.
Follow step 6, “Remove obsolete environment settings,” under Migrate from an older plugin version to clean up these variables.

​
Connect to Braintrust MCP

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

​
Set up the MCP server

1

Install Claude Code

If you haven’t already, install the Claude Code CLI or the Claude Code desktop app.
2

Add the Braintrust MCP server

To connect Claude Code to the Braintrust MCP server, Braintrust previously published a braintrust plugin. However, the plugin has been retired in favor of Claude Code’s native MCP configuration. If you installed the plugin, remove it before configuring the direct connection below.Check whether the plugin is still installed:
If braintrust@braintrust-claude-plugin appears in the list, use its scope value to remove it:
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.
From the terminal, configure Claude Code’s connection to the Braintrust MCP server. Choose whether to make it available only in the current project or across all of your projects:
Claude stores this local-scope configuration in ~/.claude.json under the current project’s path.
Both scopes work in the Claude Code CLI and in local Code-tab sessions of the desktop app. They do not apply to standard Chat or Cowork, which use connectors.These commands add the server but do not authenticate it. See Authentication for API-key setup and Endpoints for EU and self-hosted URLs.
3

Authenticate

Start the OAuth flow:
MCP authentication is separate from bt login, which authenticates the CLI and tracing integration.
4

Verify the connection

Open or restart Claude Code in the interface you use:
  • CLI: Start Claude Code and run /mcp to confirm that the Braintrust server is connected.
  • Code tab: Start a local session. For local scope, open the project where you ran claude mcp add. For user scope, open any project.
Ask Claude Code to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.

​
Use MCP tools

Once connected, 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 for more workflows and example prompts.

​
Troubleshooting MCP

Run /mcp and confirm that the Braintrust remote server is registered and connected. Restart Claude Code after adding or changing the server.For a local-scope server in the Code tab, confirm that the local session opened the same project where you ran claude mcp add.
Run /mcp to retry authentication. For authentication methods, regional and self-hosted endpoints, and network requirements, see the Braintrust MCP guide.

​
Next steps