> ## 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](/docs/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, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

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

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

## Trace Claude Code sessions

The [`trace-claude-code` plugin](https://github.com/braintrustdata/braintrust-claude-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](/docs/reference/cli/trace) to build and send traces to Braintrust.
* Authentication happens through [`bt login`](/docs/reference/cli/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](#what-gets-traced) for details.

### Set up tracing

<Note>
  Upgrading from `trace-claude-code` before v2.0.1? See [Upgrade](#upgrade).
</Note>

<Steps>
  <Step title="Install Claude Code">
    If you haven't already, install the [Claude Code CLI](https://code.claude.com/docs/en/overview) or the [desktop app](https://claude.com/product/claude-code).
  </Step>

  <Step title="Install bt and authenticate">
    Tracing runs through the `bt` CLI, so [install it](/docs/reference/cli/quickstart#install) and [authenticate](/docs/reference/cli/quickstart#authenticate-and-set-context):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    curl -fsSL https://bt.dev/cli/install.sh | bash
    bt login
    ```

    You can also install with [mise](/docs/reference/cli/quickstart#install-with-mise) or [npm](/docs/reference/cli/quickstart#install-with-npm), or with [PowerShell on Windows](/docs/reference/cli/quickstart#install).
  </Step>

  <Step title="Configure the plugin">
    After `bt` is installed and authenticated, run the following command:

    <Tabs>
      <Tab title="Terminal" icon="terminal">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        bt trace setup claude --project my-project   # Replace with your project name
        ```
      </Tab>

      <Tab title="Desktop app" icon="mouse-pointer-2">
        The desktop app shares plugin configuration with the CLI, so run setup in any terminal and it applies to desktop sessions too:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        bt trace setup claude --project my-project   # Replace with your project name
        ```
      </Tab>
    </Tabs>

    This command:

    * Adds the Braintrust plugin marketplace.
    * Installs `trace-claude-code` through Claude Code's plugin manager.
    * Selects a project.
    * Enables tracing.

    <Note>
      To learn what this command writes and how to change it later, see [Settings](#settings).
    </Note>
  </Step>

  <Step title="Restart Claude Code">
    Exit any running Claude Code sessions and start a new one so the plugin's hooks load.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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`](/docs/reference/cli/trace#bt-trace-setup) saves your tracing configuration to `~/.claude/braintrust.json`. These saved settings control where traces go during normal Claude Code sessions.

| Setting             | Saved key                   | How to change it                                                                                                                                                                                                                                        |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable tracing      | `trace_to_braintrust`       | Set `trace_to_braintrust` to `true` or `false` in `~/.claude/braintrust.json`. Re-running `bt trace setup claude` also re-enables tracing.                                                                                                              |
| Project             | `route.destination`         | Re-run `bt trace setup claude` with `--project`.                                                                                                                                                                                                        |
| `bt` profile        | `route.auth.profile`        | Re-run `bt trace setup claude` with `--profile` (the profile must already be logged in with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context)).                                                                                      |
| Organization        | `route.auth.org_name`       | Re-run `bt trace setup claude` with `--org`.                                                                                                                                                                                                            |
| Extra span metadata | `route.additional_metadata` | Edit `route.additional_metadata` in `~/.claude/braintrust.json` to save metadata, or set `BRAINTRUST_ADDITIONAL_METADATA` for sessions launched with that environment variable. If both are present, the environment variable replaces the saved value. |

Notes:

* Credentials are stored by `bt`, not the configuration file. Authenticate with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context) or `BRAINTRUST_API_KEY`. See [credential precedence](/docs/reference/cli/overview#credential-precedence).
* To use different settings for one launched session without changing saved configuration, use [`bt trace run`](/docs/reference/cli/trace#bt-trace-run).

### Common workflows

<Accordion title="Use custom settings for one run">
  To use temporary tracing settings for one interactive Claude Code session, launch Claude Code with [`bt trace run`](/docs/reference/cli/trace#bt-trace-run):

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  bt trace run --project scratch-project claude
  ```

  This command can send one run to a different project, profile, or organization without changing the saved settings in `~/.claude/braintrust.json`.
</Accordion>

<Accordion title="Trace saved Claude Code sessions">
  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:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  bt trace import claude <session-id>
  ```

  To attach the imported session below an existing Braintrust span, pass `--parent`. See [`bt trace import`](/docs/reference/cli/trace#bt-trace-import) for details, including following a live session with `--attach`.
</Accordion>

<Accordion title="Resume a Claude Code session">
  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.
</Accordion>

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

<Steps>
  <Step title="Update bt">
    Update `bt` before updating `trace-claude-code`.

    <Note>
      If you're also migrating from an older `bt` version with `bt auth` commands, review the [CLI migration guide](/docs/reference/cli/migrate). It explains how saved logins carry over, how profiles and organizations changed, and which commands replaced the old auth commands.
    </Note>

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt update
    ```

    `bt update` updates installs made with the standalone shell or PowerShell installer. If you installed with [mise](/docs/reference/cli/quickstart#install-with-mise) or [npm](/docs/reference/cli/quickstart#install-with-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](/docs/reference/cli/quickstart#install).
  </Step>

  <Step title="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`](/docs/reference/cli/quickstart#authenticate-and-set-context). You can also authenticate with `BRAINTRUST_API_KEY`.
  </Step>

  <Step title="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.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace setup claude --project my-project   # Replace with your project name
    ```

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

  <Step title="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:

    | Before v2.0.1                                         | Starting in v2.0.1                                                                                                                                                                                                                                                 |
    | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `BRAINTRUST_API_KEY`                                  | Authentication happens through `bt`. Use [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context), or continue using `BRAINTRUST_API_KEY`.                                                                                                             |
    | `TRACE_TO_BRAINTRUST=true`                            | Run `bt trace setup claude`, which saves `trace_to_braintrust: true` in `~/.claude/braintrust.json`, then remove the variable.                                                                                                                                     |
    | `BRAINTRUST_CC_PROJECT`                               | Pass its value to `bt trace setup claude --project <name>`, which saves `route.destination` in `~/.claude/braintrust.json`, then remove the variable. The old default was `claude-code`.                                                                           |
    | `CC_PARENT_SPAN_ID`, `CC_ROOT_SPAN_ID`                | Remove these variables. They no longer attach a running Claude Code session below another Braintrust span. To attach a finished session below an existing span, run [`bt trace import claude <session-id> --parent <span>`](/docs/reference/cli/trace#bt-trace-import). |
    | `BRAINTRUST_CC_DEBUG`, `BRAINTRUST_FLUSH_ON_TURN_END` | Remove these variables. The plugin no longer reads them.                                                                                                                                                                                                           |
  </Step>
</Steps>

For current settings and how to change them, see [Settings](#settings).

### Troubleshooting

<Accordion title="Traces do not appear">
  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`](/docs/reference/cli/quickstart#authenticate-and-set-context).
  * 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.
</Accordion>

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

<Steps>
  <Step title="Install Claude Code">
    If you haven't already, install the [Claude Code CLI](https://code.claude.com/docs/en/overview) or the [desktop app](https://claude.com/product/claude-code).
  </Step>

  <Step title="Add the Braintrust plugin marketplace">
    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. Add Braintrust's so the `braintrust` plugin is available to install.

    <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">
        Add the marketplace from the **Plugins** panel:

        1. Click <Icon icon="plus" /> next to the prompt box.
        2. Select **Plugins** > **Add plugin**.
        3. Enter `braintrustdata/braintrust-claude-plugin`.

        You can also run the equivalent slash command:

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

  <Step title="Install the plugin">
    Install `braintrust` from the marketplace you just added.

    <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">
    The plugin authenticates with `BRAINTRUST_API_KEY`. You only need to set it in one location.

    <Tabs>
      <Tab title="Terminal" icon="terminal">
        If the key is set in more than one location, Claude Code applies this [precedence order](https://code.claude.com/docs/en/settings), from 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>

  <Step title="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.
  </Step>
</Steps>

### 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](/docs/integrations/developer-tools/mcp#tools).

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

<Accordion title="Braintrust MCP tools do not appear">
  * 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.
</Accordion>

<Accordion title="MCP authentication fails">
  * 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](https://www.braintrust.dev) using the account associated with the API key.
  * Generate a new API key if needed.
</Accordion>

<Accordion title="MCP connection errors">
  * The plugin connects to `$BRAINTRUST_API_URL/mcp`, defaulting to `https://api.braintrust.dev/mcp`. If your organization is on the [EU data plane](/docs/admin/organizations#data-plane-region), 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.
</Accordion>

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace), including session imports and per-run tracing.
* **Run evaluations**: Check out the [evaluation guide](/docs/evaluate/run-evaluations) to learn evaluation patterns.
* **Explore MCP tools**: See the [MCP documentation](/docs/integrations/developer-tools/mcp#tools) for all available commands.
* **Browse the source**: The [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins) contains the plugin source code.