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.
This guide covers both plugins and how to use them together.

​
Setup

1

Prerequisites

Before installing the Braintrust plugins, ensure you have Claude Code and jq installed:Install Claude Code:
curl -fsSL https://claude.ai/install.sh | bash
Install the jq JSON processor, which the tracing hooks use to parse Claude Code’s output:
brew install jq
2

Install the plugins

Install the Braintrust plugin marketplace, the tracing plugin for automatic observability, and the operations plugin to enable Claude for querying logs and running evaluations:
claude plugin marketplace add braintrustdata/braintrust-claude-plugin
claude plugin install trace-claude-code@braintrust-claude-plugin
claude plugin install braintrust@braintrust-claude-plugin
It’s not required to install both plugins. Install only the ones you need.
3

Run the setup script

The setup script will prompt you for your Braintrust API key and project name:
# Only required for trace-claude-code plugin
~/.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, check your Claude Code settings for the plugins directory location.

​
Braintrust plugin

The braintrust plugin brings Braintrust data and context directly into Claude Code by connecting to Braintrust’s MCP server. You can fetch experiment results, query logs, log data, and more. See MCP documentation for details.

​
Trace Claude Code plugin

The trace-claude-code plugin captures every operation Claude Code performs, helping you:
  • Debug issues by seeing exactly what tools Claude ran
  • Monitor team usage and patterns
  • Understand LLM call costs and performance
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"}}' \
  -p "your task"
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"}}' \
  -p "your task"
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.

​
Update config

After initial setup, you can update the plugin configuration by editing the variables in your project’s .claude/settings.local.json file or global claude code config in ~/.claude/settings.json.
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.
{
  "env": {
    "TRACE_TO_BRAINTRUST": "false",
    "BRAINTRUST_CC_PROJECT": "your-project-name",
    "BRAINTRUST_API_KEY": "your-api-key",
    "BRAINTRUST_CC_DEBUG": "false"
  }
}

​
Troubleshooting

Check the hook logs for errors:
tail -f ~/.claude/state/braintrust_hook.log
Verify your environment variables are set correctly in .claude/settings.local.json, and enable debug mode by setting BRAINTRUST_CC_DEBUG=true.
Make sure the hook scripts are executable:
chmod +x ~/.claude/plugins/marketplaces/braintrust-claude-plugin/plugins/trace-claude-code/*.sh
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

Now that you have both plugins set up:
  • Explore your traces: Navigate to your project in Braintrust and explore the hierarchical trace structure.
  • 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.