> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[Claude Code](https://code.claude.com/docs/en/overview) 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.

<Tip>
  Install one or both of these plugins, as needed.
</Tip>

## Prerequisites

<Steps>
  <Step title="Install Claude Code">
    If you haven't already, install [Claude Code](https://claude.com/product/claude-code).
  </Step>

  <Step title="Add the Braintrust plugin marketplace">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    claude plugin marketplace add braintrustdata/braintrust-claude-plugin
    ```

    <Note>
      A [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) is a catalog of plugins that you can browse and install into Claude Code.
    </Note>
  </Step>

  <Step title="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](https://code.claude.com/docs/en/settings) (highest to lowest):

    <AccordionGroup>
      <Accordion title="CLI flag (--settings)">
        Overrides settings files for a single session. See the [CLI reference](https://code.claude.com/docs/en/cli-reference) for details.

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        claude --settings '{"env":{"BRAINTRUST_API_KEY":"YOUR_API_KEY"}}'
        ```
      </Accordion>

      <Accordion title="Local project settings (.claude/settings.local.json)">
        This file applies only to the current project. Don't commit it to version control.

        ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        {
          "env": {
            "BRAINTRUST_API_KEY": "YOUR_API_KEY"
          }
        }
        ```
      </Accordion>

      <Accordion title="Global settings (~/.claude/settings.json)">
        Applies to all projects on your machine:

        ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        {
          "env": {
            "BRAINTRUST_API_KEY": "YOUR_API_KEY"
          }
        }
        ```
      </Accordion>

      <Accordion title="Shell profile (~/.zshrc or ~/.bashrc)">
        Lowest precedence. Overridden by any settings file:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        export BRAINTRUST_API_KEY="YOUR_API_KEY"
        ```
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

***

## Plugin: `braintrust`

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

### Setup

<Steps>
  <Step title="Install the plugin">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    claude plugin install braintrust@braintrust-claude-plugin
    ```
  </Step>

  <Step title="Set your API key">
    Set `BRAINTRUST_API_KEY` as described in the [Prerequisites](#prerequisites).
  </Step>

  <Step title="Restart Claude Code">
    Exit any running Claude Code sessions and start a new one. The plugin reads your API key when Claude Code starts.
  </Step>
</Steps>

### 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](/integrations/developer-tools/mcp#available-tools) for the full list of available tools.

### Troubleshooting

<Accordion title="Needs authentication">
  Verify that `BRAINTRUST_API_KEY` is set in your Claude Code session:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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.
</Accordion>

## 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](https://code.claude.com/docs/en/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

<Steps>
  <Step title="Install the plugin">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    claude plugin install trace-claude-code@braintrust-claude-plugin
    ```
  </Step>

  <Step title="Install jq">
    The tracing hooks use [`jq`](https://jqlang.org/) to parse Claude Code's output:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    brew install jq
    ```
  </Step>

  <Step title="Configure tracing">
    Make sure `BRAINTRUST_API_KEY` is set as described in [Prerequisites](#prerequisites), then add the following tracing settings to `~/.claude/settings.json` (global), `.claude/settings.local.json` (project), or your shell profile:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    {
      "env": {
        "TRACE_TO_BRAINTRUST": "true",
        "BRAINTRUST_CC_PROJECT": "YOUR_PROJECT_NAME"
      }
    }
    ```

    Alternatively, run the setup script to configure a project directory interactively:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    ~/.claude/plugins/marketplaces/braintrust-claude-plugin/plugins/trace-claude-code/setup.sh
    ```

    <Note>
      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](https://code.claude.com/docs/en/plugins-reference#plugin-caching-and-file-resolution) for details on where Claude Code stores installed plugins.
    </Note>
  </Step>
</Steps>

### Configuration

Required settings:

| Setting               | Description                             | Default |
| --------------------- | --------------------------------------- | ------- |
| `TRACE_TO_BRAINTRUST` | Must be set to `true` to enable tracing | —       |
| `BRAINTRUST_API_KEY`  | Your Braintrust API key                 | —       |

Optional settings:

| Setting                 | Description                                                 | Default       |
| ----------------------- | ----------------------------------------------------------- | ------------- |
| `BRAINTRUST_CC_PROJECT` | Braintrust project to send traces to                        | `claude-code` |
| `BRAINTRUST_CC_DEBUG`   | Write verbose logs to `~/.claude/state/braintrust_hook.log` | `false`       |

<Note>
  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.
</Note>

### Usage

Start a Claude Code session:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://braintrust.dev) and select <Icon icon="activity" /> **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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

<Accordion title="No traces appearing">
  Check the hook logs for errors:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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`.
</Accordion>

<Accordion title="State issues">
  If traces seem corrupted or incomplete, try resetting the state file:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  rm ~/.claude/state/braintrust_state.json
  ```

  Then start a new Claude Code session.
</Accordion>

## 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](https://braintrust.dev).
* **Run evaluations**: Check out the [evaluation guide](/evaluate/run-evaluations) to learn evaluation patterns.
* **Browse examples**: The [braintrust-claude-plugin repository](https://github.com/braintrustdata/braintrust-claude-plugin) includes evaluation suites that demonstrate the plugin's capabilities.