Skip to main content
Claude Code is Anthropic’s agentic coding tool, available as a terminal CLI and a desktop app. You can integrate Claude Code with Braintrust in two ways:
  • Trace Claude Code sessions: Log your Claude Code sessions to Braintrust, including session, turn, model call, tool, and subagent spans.
  • Connect to the Braintrust MCP server: Let Claude Code access your Braintrust projects, experiments, logs, and other data during a session.
The Claude Code desktop app shares its configuration with the CLI, so the same plugins and hooks work in both. This guide covers each setup interface.

​
Trace Claude Code sessions

The trace-claude-code plugin traces your Claude Code sessions to Braintrust by observing Claude Code, not by proxying it:
  • Claude Code talks to its model provider directly.
  • Hooks notify the plugin when sessions start, prompts arrive, tools run, and sessions finish.
  • The plugin uses the bt CLI to build and send traces to Braintrust.
  • Authentication happens through bt login. The plugin never handles credentials.
  • If the plugin or bt has a problem, Claude Code keeps working. However, you won’t see traces until the setup is fixed.
Each Claude Code session appears in Braintrust as one trace with session, turn, model call, tool, and subagent spans. See What gets traced for details.

​
Set up tracing

Upgrading from trace-claude-code before v2.0.1? See Upgrade.
1

Install Claude Code

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

Install bt and authenticate

Tracing runs through the bt CLI, so install it and authenticate:
You can also install with mise or npm, or with PowerShell on Windows.
3

Configure the plugin

After bt is installed and authenticated, run the following command:
This command:
  • Adds the Braintrust plugin marketplace.
  • Installs trace-claude-code through Claude Code’s plugin manager.
  • Selects a project.
  • Enables tracing.
To learn what this command writes and how to change it later, see Settings.
4

Restart Claude Code

Exit any running Claude Code sessions and start a new one so the plugin’s hooks load.
5

Log a test trace

Start a short Claude Code session and ask it to do something simple. When the session finishes, open your Braintrust project and check that the trace appears in Logs.

​
What gets traced

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 as trace_claude_code_version.

​
Settings

bt trace setup claude saves your tracing configuration to ~/.claude/braintrust.json. These saved settings control where traces go during normal Claude Code sessions. Notes:
  • Credentials are stored by bt, not the configuration file. Authenticate with bt login or BRAINTRUST_API_KEY. See credential precedence.
  • To use different settings for one launched session without changing saved configuration, use bt trace run.

​
Common workflows

To use temporary tracing settings for one interactive Claude Code session, launch Claude Code with bt trace run:
This command can send one run to a different project, profile, or organization without changing the saved settings in ~/.claude/braintrust.json.
Claude Code keeps a transcript of every session on disk, so you can send a past session to Braintrust and get its trace after the fact. This works even if tracing wasn’t set up when the session ran:
To attach the imported session below an existing Braintrust span, pass --parent. See bt trace import for details, including following a live session with --attach.
When you resume a Claude Code session, the trace continues in the same root span. Span identities derive from the session ID, so later turns attach to the original trace even after the background tracing process has restarted.

​
Upgrade

To get the latest bt and trace-claude-code, follow these steps. If you are upgrading from trace-claude-code before v2.0.1, the steps also cover the required migration.
1

Update bt

Update bt before updating trace-claude-code.
If you’re also migrating from an older bt version with bt auth commands, review the CLI migration guide. It explains how saved logins carry over, how profiles and organizations changed, and which commands replaced the old auth commands.
bt update updates installs made with the standalone shell or PowerShell installer. If you installed with mise or npm, update bt with that package manager instead. If a Windows install older than bt v0.17.0 cannot update itself, rerun the PowerShell installer.
2

Authenticate bt

Starting in v2.0.1, trace-claude-code uses bt for tracing and authentication. If you haven’t authenticated with bt, run bt login. You can also authenticate with BRAINTRUST_API_KEY.
3

Run setup

Run setup with the Braintrust project that should receive your Claude Code traces. This installs or updates trace-claude-code and writes the latest tracing settings.
Before v2.0.1, the plugin read the destination project from the BRAINTRUST_CC_PROJECT environment variable. If you are upgrading from one of these versions, find its value under env in ~/.claude/settings.json or your project’s .claude/settings.local.json, or in your shell profile. In the command above, replace my-project with that value. If you did not set the variable, use claude-code, the old default. bt trace setup does not migrate this value automatically.
4

Migrate settings from a plugin version before v2.0.1

If you are upgrading from a plugin version before v2.0.1, use this table to migrate environment variables set under env in ~/.claude/settings.json or your project’s .claude/settings.local.json, or in your shell profile:
For current settings and how to change them, see Settings.

​
Troubleshooting

Check the following, in order:
  • Confirm the plugin is installed and enabled: run claude plugin list and check that trace-claude-code appears.
  • Verify bt is installed and current: bt --version (v0.16.0 or later).
  • Verify bt is authenticated: run bt status. If it shows no active login, run bt login.
  • Verify tracing is enabled: in ~/.claude/braintrust.json, confirm that trace_to_braintrust is true and route.destination names the intended project.
  • Check the background process: bt trace status shows whether the tracing daemon is running.
  • Restart Claude Code after any configuration change.
Tracing failures don’t interrupt Claude Code, so your Claude Code session can keep working even when traces do not appear.

​
Connect to the Braintrust MCP server

Claude Code can use Braintrust’s MCP server to access your projects, experiments, and logs. The braintrust plugin connects Claude Code to that server.

​
Set up the MCP server

1

Install Claude Code

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

Add the Braintrust plugin marketplace

A plugin marketplace is a catalog of plugins that you can browse and install into Claude Code. Add Braintrust’s so the braintrust plugin is available to install.
3

Install the plugin

Install braintrust from the marketplace you just added.
4

Set your API key

The plugin authenticates with BRAINTRUST_API_KEY. You only need to set it in one location.
If the key is set in more than one location, Claude Code applies this precedence order, from highest to lowest:
Overrides settings files for a single session. See the CLI reference for details.
This file applies only to the current project. Don’t commit it to version control.
Applies to all projects on your machine:
Lowest precedence. Overridden by any settings file:
5

Verify the setup

Exit any running Claude Code sessions and start a new one. The plugin reads your API key when Claude Code starts.Run /mcp to verify Braintrust is installed and accessible.

​
Use MCP tools

Once configured, Claude Code can access Braintrust data through the MCP server. You can fetch experiment results, query logs, log data, and more. For the full list of available tools, see the MCP documentation. Example prompts in Claude Code:
  • “Show me my recent Braintrust experiments”
  • “Query the last 10 logged requests with errors”
  • “What’s the average latency for the summarizer prompt today?”
  • “Compare accuracy scores between my two latest experiments”

​
Troubleshooting

  • Confirm the plugin is installed and enabled: run claude plugin list and check that braintrust appears.
  • Restart Claude Code after installing the plugin or changing configuration.
  • Run /mcp in Claude Code to see available MCP servers.
  • Verify your API key is correct (no extra spaces).
  • Check the location where you set the key: ~/.claude/settings.json (global), .claude/settings.local.json (project), or your shell profile. Keys set in a settings file are passed to the plugin rather than to your terminal, so they won’t appear in your shell environment.
  • Claude Code reads the key at startup, so exit any running sessions and start a new one after changing it.
  • Ensure you can log into Braintrust using the account associated with the API key.
  • Generate a new API key if needed.
  • The plugin connects to $BRAINTRUST_API_URL/mcp, defaulting to https://api.braintrust.dev/mcp. If your organization is on the EU data plane, set BRAINTRUST_API_URL to https://api-eu.braintrust.dev.
  • Corporate networks may need to allowlist the configured Braintrust API host: api.braintrust.dev for the US data plane or api-eu.braintrust.dev for the EU data plane. Allowlist *.braintrust.dev if your network also filters browser sign-in or app links.

​
Next steps