> ## 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

> Connect Braintrust to Claude Code in the terminal or desktop app with the braintrust and trace-claude-code plugins to query data and trace sessions.

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, available as a terminal CLI and a desktop app. Braintrust provides two complementary plugins that work in both:

* **`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.

<Note>
  The Claude Code desktop app shares its configuration with the CLI, so the same plugins, API key, and hooks work in both. This guide covers each setup interface.
</Note>

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

    <Tabs>
      <Tab title="Terminal" icon="terminal">
        Follow the [installation guide](https://code.claude.com/docs/en/overview) to install the Claude Code CLI.
      </Tab>

      <Tab title="Desktop app" icon="mouse-pointer-2">
        Download the [Claude Code desktop app](https://claude.com/product/claude-code), sign in with your Anthropic account, and open the **Code** tab.
      </Tab>
    </Tabs>
  </Step>

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

      <Tab title="Desktop app" icon="mouse-pointer-2">
        Click <Icon icon="plus" /> next to the prompt box, select **Plugins** > **Add plugin**, then add the marketplace `braintrustdata/braintrust-claude-plugin`. You can also run the equivalent slash command:

        ```
        /plugin marketplace add braintrustdata/braintrust-claude-plugin
        ```
      </Tab>
    </Tabs>

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

    <Tabs>
      <Tab title="Terminal" icon="terminal">
        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>
      </Tab>

      <Tab title="Desktop app" icon="mouse-pointer-2">
        Click the environment dropdown in the prompt box, hover over **Local**, and click the gear icon to open the local environment editor. Add your key:

        ```
        BRAINTRUST_API_KEY=YOUR_API_KEY
        ```

        The desktop app also reads the same settings files as the CLI, so any of the terminal options work as well.
      </Tab>
    </Tabs>
  </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">
    <Tabs>
      <Tab title="Terminal" icon="terminal">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        claude plugin install braintrust@braintrust-claude-plugin
        ```
      </Tab>

      <Tab title="Desktop app" icon="mouse-pointer-2">
        In the **Plugins** panel, select **braintrust** from the marketplace and install it, or run:

        ```
        /plugin install braintrust@braintrust-claude-plugin
        ```
      </Tab>
    </Tabs>
  </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">
    <Tabs>
      <Tab title="Terminal" icon="terminal">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        claude plugin install trace-claude-code@braintrust-claude-plugin
        ```
      </Tab>

      <Tab title="Desktop app" icon="mouse-pointer-2">
        In the **Plugins** panel, select **trace-claude-code** from the marketplace and install it, or run:

        ```
        /plugin install trace-claude-code@braintrust-claude-plugin
        ```
      </Tab>
    </Tabs>
  </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 in the terminal with `claude`, or open the desktop app.

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.