Skip to main content
Claude Code is Anthropic’s agentic coding tool that lives in your terminal. Braintrust provides two complementary plugins for Claude Code:
  • braintrust: Brings context (docs, logs, experiments) from Braintrust into your programming environment. For example, query logs, access Braintrust docs, or fetch experiment results when writing evaluations.
  • trace-claude-code: Traces Claude Code’s operations to show LLM calls, tool usage, and timing data. This can be useful for personal exploration or to monitor your team’s activity.
Install one or both of these plugins, as needed.

​
Prerequisites

1

Install Claude Code

If you haven’t already, install Claude Code.
2

Add the Braintrust plugin marketplace

claude plugin marketplace add braintrustdata/braintrust-claude-plugin
A plugin marketplace is a catalog of plugins that you can browse and install into Claude Code.
3

Set your API key

Both plugins authenticate using BRAINTRUST_API_KEY. You only need to set it in one location. Global settings are recommended if you use Braintrust across multiple projects.If the key is set in multiple locations, Claude Code applies this precedence order (highest to lowest):
Overrides settings files for a single session. See the CLI reference for details.
claude --settings '{"env":{"BRAINTRUST_API_KEY":"YOUR_API_KEY"}}'
This file applies only to the current project. Don’t commit it to version control.
{
  "env": {
    "BRAINTRUST_API_KEY": "YOUR_API_KEY"
  }
}
Applies to all projects on your machine:
{
  "env": {
    "BRAINTRUST_API_KEY": "YOUR_API_KEY"
  }
}
Lowest precedence. Overridden by any settings file:
export BRAINTRUST_API_KEY="YOUR_API_KEY"

​
Plugin: braintrust

The braintrust plugin brings Braintrust data and context directly into Claude Code by connecting to Braintrust’s MCP server.

​
Setup

1

Install the plugin

claude plugin install braintrust@braintrust-claude-plugin
2

Set your API key

Set BRAINTRUST_API_KEY as described in the Prerequisites.
3

Restart Claude Code

Exit any running Claude Code sessions and start a new one. The plugin reads your API key when Claude Code starts.

​
Usage

Once installed, you can ask Claude Code to work with your Braintrust data directly:
  • “Compare my experiment against the baseline”
  • “Show me the last 10 logged requests with errors”
  • “What fields are available in my experiment data?”
  • “How do I create a custom scorer?”
See MCP documentation for the full list of available tools.

​
Troubleshooting

Verify that BRAINTRUST_API_KEY is set in your Claude Code session:
echo $BRAINTRUST_API_KEY
If it’s empty, make sure the key is set in ~/.claude/settings.json (global), .claude/settings.local.json (project), or your shell profile, then restart Claude Code.

​
Plugin: trace-claude-code

The trace-claude-code plugin automatically traces Claude Code sessions to Braintrust, helping you:
  • Debug issues by seeing exactly what tools Claude ran
  • Monitor team usage and patterns
  • Understand LLM call costs and performance
The plugin works by registering Claude Code hooks for each interaction in a session — session start, user prompts, tool calls, and session end. Each session becomes a single trace in Braintrust, with turns and tool calls nested as child spans.

​
Setup

1

Install the plugin

claude plugin install trace-claude-code@braintrust-claude-plugin
2

Install jq

The tracing hooks use jq to parse Claude Code’s output:
brew install jq
3

Configure tracing

Make sure BRAINTRUST_API_KEY is set as described in Prerequisites, then add the following tracing settings to ~/.claude/settings.json (global), .claude/settings.local.json (project), or your shell profile:
{
  "env": {
    "TRACE_TO_BRAINTRUST": "true",
    "BRAINTRUST_CC_PROJECT": "YOUR_PROJECT_NAME"
  }
}
Alternatively, run the setup script to configure a project directory interactively:
~/.claude/plugins/marketplaces/braintrust-claude-plugin/plugins/trace-claude-code/setup.sh
The plugin directory path may vary depending on your Claude Code configuration. If the path above doesn’t exist, see plugin caching and file resolution for details on where Claude Code stores installed plugins.

​
Configuration

Required settings:
SettingDescriptionDefault
TRACE_TO_BRAINTRUSTMust be set to true to enable tracing—
BRAINTRUST_API_KEYYour Braintrust API key—
Optional settings:
SettingDescriptionDefault
BRAINTRUST_CC_PROJECTBraintrust project to send traces toclaude-code
BRAINTRUST_CC_DEBUGWrite verbose logs to ~/.claude/state/braintrust_hook.logfalse
Configuration changes take effect the next time you start a Claude Code session. Exit any running sessions and start a new one to apply your changes.

​
Usage

Start a Claude Code session: 
claude
The plugin automatically traces each session as a hierarchy of spans:
  • Session root: The overall Claude Code session from start to finish
  • Turns: Individual conversation exchanges (your input → Claude’s response)
  • Tool calls: Operations like file reads, edits, terminal commands, and searches
Each trace includes rich metadata:
  • Session ID and workspace location
  • Turn numbers and conversation content
  • Tool names with inputs and outputs
  • Span attributes indicating type (“task”, “llm”, “tool”)
To view your traces in real-time, go to your project in the Braintrust UI and select Logs.

​
Embed traces in parent traces

You can embed Claude Code traces inside a parent trace when using Claude Code as part of a larger workflow. This enables better observability by showing Claude Code’s execution context within your broader application traces. To attach a Claude Code session to an existing Braintrust trace, pass the CC_PARENT_SPAN_ID environment variable: 
claude --settings '{"env":{"CC_PARENT_SPAN_ID":"your-parent-span-id"}}'
When the parent span is not the root of your trace hierarchy, you must also supply CC_ROOT_SPAN_ID to maintain proper trace relationships: 
claude --settings '{"env":{"CC_PARENT_SPAN_ID":"parent-span-id","CC_ROOT_SPAN_ID":"root-span-id"}}'
Once configured, the Claude Code session and all its turns and tool calls will appear as children of your parent span in Braintrust, creating a hierarchical visualization of your conversation and tool interactions within your existing trace.

​
Troubleshooting

Check the hook logs for errors:
tail -f ~/.claude/state/braintrust_hook.log
Verify your environment variables are set correctly and that TRACE_TO_BRAINTRUST is true. Enable debug mode by setting BRAINTRUST_CC_DEBUG=true.
If traces seem corrupted or incomplete, try resetting the state file:
rm ~/.claude/state/braintrust_state.json
Then start a new Claude Code session.

​
Next steps

  • Query your data: Use the braintrust plugin to explore experiments, logs, and datasets from Claude Code.
  • Explore your traces: View Claude Code session traces in the Braintrust UI.
  • Run evaluations: Check out the evaluation guide to learn evaluation patterns.
  • Browse examples: The braintrust-claude-plugin repository includes evaluation suites that demonstrate the plugin’s capabilities.