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

# OpenCode

> Trace OpenCode sessions to Braintrust and access your Braintrust data through built-in tools or MCP

[OpenCode](https://opencode.ai) is an open-source AI coding assistant. You can connect it to Braintrust in two ways:

* **Trace OpenCode sessions** to record session, turn, model call, tool, and subagent spans in Braintrust.
* **Connect to Braintrust MCP** to work with Braintrust projects, experiments, logs, and other data from OpenCode.

## Trace OpenCode sessions

The [`@braintrust/trace-opencode` plugin](https://www.npmjs.com/package/@braintrust/trace-opencode) passes your interactions with OpenCode to `bt`, which in turn uses a background process to build and deliver the trace to Braintrust.

OpenCode continues to communicate directly with its model provider, and tracing failures do not stop your OpenCode session. The plugin also provides [built-in Braintrust tools](#built-in-braintrust-tools), independently of MCP.

### Set up tracing

<Note>
  If `@braintrust/trace-opencode` is already installed, follow [Update the tracing plugin](#update-the-tracing-plugin).
</Note>

<Steps>
  <Step title="Install OpenCode">
    If you haven't already, install [OpenCode](https://opencode.ai/). The plugin requires OpenCode v1.2.25 or later.
  </Step>

  <Step title="Install and authenticate bt">
    Follow the [`bt` CLI quickstart](/docs/reference/cli/quickstart) to install `bt` v0.19.3 or later, authenticate, and set your active context.
  </Step>

  <Step title="Enable tracing">
    <a id="settings" />

    Before starting OpenCode, run this command in a terminal:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable opencode --project <your-project>
    ```

    This command:

    * Adds or updates [`@braintrust/trace-opencode`](https://www.npmjs.com/package/@braintrust/trace-opencode) in your global `~/.config/opencode/opencode.json`, using the `^2` version range.
    * Writes `~/.config/opencode/braintrust.json`, which records whether tracing is enabled and which project receives traces.

    The tracing file stores settings, not credentials. If `XDG_CONFIG_HOME` is set, both configuration files are under `$XDG_CONFIG_HOME/opencode/` instead. A project's `.opencode/braintrust.json` can override the global tracing settings.

    For more information, see [`bt trace enable`](/docs/reference/cli/trace#bt-trace-enable).
  </Step>

  <Step title="Restart OpenCode">
    Restart OpenCode so it loads the plugin and tracing settings.
  </Step>

  <Step title="Log a test trace">
    Ask OpenCode to do something simple. When the session finishes, open your Braintrust project and confirm that the trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page.
  </Step>
</Steps>

### What Braintrust traces

<a id="what-gets-traced" />

OpenCode traces in Braintrust include:

* Session spans with the session ID, local username, and Git repository metadata.
* Turn spans with prompts, model names, and requested skills.
* Model call spans with conversation input, response output, errors, and token metrics.
* Tool spans with inputs and outputs, including skill loads.
* Subagent spans nested under the parent session's active turn when the parent is available.

Every span records its origin as `braintrust.plugin.opencode`.

### Common workflows

<AccordionGroup>
  <Accordion title="Use different tracing settings for one session">
    Use [`bt trace run`](/docs/reference/cli/trace#bt-trace-run) to trace a single OpenCode invocation without changing the saved tracing configuration.

    This workflow launches OpenCode from the terminal.

    To change the saved destination, profile, or organization, rerun [`bt trace enable opencode`](/docs/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](/docs/reference/cli/switch) does not change the saved tracing configuration.

    To add root-span metadata, pass `--additional-metadata '<JSON>'` to `bt trace run` for one invocation or to `bt trace enable` for future sessions. Standard session metadata takes precedence when keys conflict.

    With `bt` v0.19.3 or later, pass `--tag ci --tag release-validation` to either command to [tag session spans](/docs/reference/cli/trace#tag-traces).
  </Accordion>

  <Accordion title="Stop tracing OpenCode sessions">
    Use [`bt trace disable opencode`](/docs/reference/cli/trace#bt-trace-disable) to remove the tracing plugin from the global OpenCode configuration and remove its global tracing configuration. Saved `bt` profiles and credentials are preserved. Restart OpenCode afterward.

    Removing the plugin also removes its built-in Braintrust tools. To stop tracing while keeping those tools, set `trace_to_braintrust` to `false` in the effective tracing file instead.

    If you also registered the plugin in a project configuration, remove that registration to stop tracing there.
  </Accordion>
</AccordionGroup>

### Built-in Braintrust tools

The tracing plugin also registers tools that call `bt` to access Braintrust data, without an MCP connection:

* `braintrust_query_logs`: Query logs with SQL.
* `braintrust_list_projects`: List projects.
* `braintrust_get_experiments`: List recent experiments.
* `braintrust_log_data`: Upload data to project logs.

These tools are enabled by default. To keep tracing without registering them, set `enable_tools` to `false` in the global or project-local tracing file. `BRAINTRUST_OPENCODE_ENABLE_TOOLS` overrides that setting.

### Update the tracing plugin

To update the plugin, follow these steps:

<Note>
  If `opencode debug config` shows `@braintrust/trace-opencode` earlier than v2.0.0 in the `plugin` list, or you cannot determine its version, follow [Migrate from an older plugin version](#migrate-from-an-older-plugin-version).
</Note>

<Steps>
  <Step title="Update bt">
    Follow the [CLI migration guide](/docs/reference/cli/migrate) to update `bt` to the latest version and complete the applicable migrations.
  </Step>

  <Step title="Update the tracing plugin">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace update opencode
    ```

    [`bt trace update`](/docs/reference/cli/trace#bt-trace-update) updates the plugin's package specification in the global OpenCode configuration without changing your saved tracing configuration.
  </Step>

  <Step title="Restart and verify OpenCode">
    Restart OpenCode, run a short session, and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.
  </Step>
</Steps>

### Migrate from an older plugin version

<a id="upgrade" />

To migrate to the latest version of the `@braintrust/trace-opencode` plugin, follow these steps:

<Steps>
  <Step title="Inspect your OpenCode plugins">
    Inspect your active OpenCode configuration and find `@braintrust/trace-opencode` in the `plugin` list:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    opencode debug config
    ```

    Record the plugin's starting version before updating. Also record the profile, organization, project, metadata, and custom tracing settings you want to preserve from the global tracing file and any project-local `.opencode/braintrust.json`.

    <Note>
      If the plugin is not installed, follow [Set up tracing](#set-up-tracing). If you cannot determine the installed version from its configured version range, complete both migration sections below.
    </Note>
  </Step>

  <Step title="Install or update bt">
    These steps require `bt` v0.19.3 or later. Check whether `bt` is installed:

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

    * If the command succeeds, [migrate to the latest version](/docs/reference/cli/migrate) (unless you've already done so).
    * Otherwise, [install `bt`](/docs/reference/cli/quickstart), authenticate, and set organization and project context.
  </Step>

  <Step title="Complete version-specific migration steps">
    <Note>
      Complete each section for a version newer than your starting `@braintrust/trace-opencode` version, beginning with the oldest. If no sections apply, continue to the next step.
    </Note>

    <AccordionGroup>
      <Accordion title="@braintrust/trace-opencode v1.0.0">
        <Note>
          Complete this section if you started your migration from a plugin version earlier than v1.0.0.
        </Note>

        Before v1.0.0, the plugin handled authentication and trace delivery itself. Starting in v1.0.0, `bt` handles both, and the tracing files store settings rather than credentials.

        Record `project`, `org_name`, and `additional_metadata` from `~/.config/opencode/braintrust.json` and your project's `.opencode/braintrust.json`. Environment variables took precedence over these files. Earlier versions did not use `XDG_CONFIG_HOME`. If the project was not configured, the default was `opencode`.

        If the old configuration contains `api_key`, `api_url`, or `app_url`, use the corresponding credentials and deployment when you [authenticate with `bt`](/docs/reference/cli/login). Keep credentials private and retain any settings needed by other integrations.
      </Accordion>

      <Accordion title="@braintrust/trace-opencode v2.0.0">
        <Note>
          Complete this section if you started your migration from a plugin version earlier than v2.0.0.
        </Note>

        Before v2.0.0, the following environment variables overrode saved tracing settings. Starting in v2.0.0, the plugin no longer reads these overrides from the agent's environment. Record any values you want to preserve:

        * `TRACE_TO_BRAINTRUST`: Whether tracing was enabled.
        * `BRAINTRUST_PROFILE` and `BRAINTRUST_ORG_NAME`: The tracing account and organization.
        * `BRAINTRUST_PROJECT`: The project that received traces.
        * `BRAINTRUST_ADDITIONAL_METADATA`: Extra root-span metadata.

        <Note>
          In the next step, pass the recorded project with `--project`, account and organization with `--profile` and `--org`, and metadata with `--additional-metadata '<JSON>'`. This preserves values that previously overrode your saved configuration.
        </Note>

        v2.0.0 also changes how conflicting settings in `braintrust.json` are resolved:

        * Profile, organization, and project values in the `route` object now take precedence over their legacy top-level equivalents. Before v2.0.0, the top-level values took precedence.
        * Metadata is unchanged: top-level `additional_metadata` can still override `route.additional_metadata`.

        The next step moves your saved settings into the `route` object so you do not leave conflicting copies. Environment variables accepted by `bt` commands are separate from these plugin changes. See [`bt trace`](/docs/reference/cli/trace).
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Apply your tracing settings">
    Run this command with your intended project, using the project you recorded earlier to preserve your destination:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable opencode --project <your-project>
    ```

    Pass `--profile <profile>` and `--org <organization>` if needed to preserve your tracing account and organization. Otherwise, the command uses your active `bt` context, not your saved tracing settings.

    The command updates your global tracing file, normally `~/.config/opencode/braintrust.json`. Check the following settings in that file:

    * Existing `route.additional_metadata` is preserved unless you pass `--additional-metadata`. If it is absent, `bt` migrates top-level `additional_metadata` instead.
    * Existing `route.tags` is preserved unless you pass `--tag` or set `BRAINTRUST_TAGS`.
    * `route.flush_mode` resets to `fire_and_forget`. Restore its previous value if you customized it.
    * Restore any other custom tracing settings you recorded before updating.

    The command also removes obsolete top-level destination and authentication keys from the global tracing file. It does not migrate project-local files. For each project-local file, use the `route` object in the generated global file as a template while preserving that project's intended destination, authentication, metadata, and tags. A project-level `route` object replaces the entire global `route` object. After moving any legacy values under `route`, remove their duplicate top-level keys so they cannot override it.
  </Step>

  <Step title="Restart and verify OpenCode">
    Restart OpenCode, run a short session, and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project. Check each project where you changed local tracing settings.
  </Step>

  <Step title="Remove obsolete settings">
    <Note>
      Complete this step only if you started with a plugin version earlier than v2.0.0 and verified that traces reach the intended project in the previous step.
    </Note>

    <Accordion title="Settings used before @braintrust/trace-opencode v2.0.0">
      The plugin now reads tracing settings from its configuration files. Environment variables you previously configured for tracing may no longer be needed.

      Check these locations for leftover settings:

      * Your shell configuration
      * The global tracing file and your project's `.opencode/braintrust.json`

      Remove the settings below if they were used only for tracing. Keep any that other `bt` commands, MCP connections, or integrations still need:

      * `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, `BRAINTRUST_PROJECT`, and `BRAINTRUST_ADDITIONAL_METADATA` in the agent environment
      * `BRAINTRUST_API_KEY`, `BRAINTRUST_API_URL`, and `BRAINTRUST_APP_URL` used by pre-v1.0.0 tracing
      * Top-level `profile`, `org_name`, `project`, and `additional_metadata` after preserving their values under `route`
      * Pre-v1.0.0 `api_key`, `api_url`, `app_url`, `log_to_file`, and `queue_size` keys
      * Pre-v1.0.0 `LOG_TO_FILE` and `BRAINTRUST_QUEUE_SIZE` environment variables

      Keep `BRAINTRUST_OPENCODE_ENABLE_TOOLS` if you use it to control the built-in tools.
    </Accordion>
  </Step>
</Steps>

### Troubleshooting tracing

First, run `bt trace doctor opencode`. Then, review the following:

<AccordionGroup>
  <Accordion title="The tracing plugin is missing or disabled">
    Run `opencode debug config` and confirm that `@braintrust/trace-opencode@^2` is in the `plugin` list. If it is missing or broken, run:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace enable opencode --project <your-project>
    ```

    Restart OpenCode afterward.
  </Accordion>

  <Accordion title="Traces do not appear after setup">
    If OpenCode was running when its plugin or configuration changed, restart it.

    Run `bt trace doctor opencode` and confirm that tracing is enabled and routed to the intended project. Also inspect any project-local tracing file, which can override the global settings.

    If authentication succeeds but traces do not appear, confirm that your account has [permission to write logs to the selected project](/docs/reference/cli/trace#project-log-permissions).

    For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](/docs/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](/docs/reference/cli/migrate#troubleshooting).

    Tracing failures do not interrupt the OpenCode session.
  </Accordion>

  <Accordion title="OpenCode uses an unexpected configuration directory">
    Check whether `XDG_CONFIG_HOME` is set in the environment that launches OpenCode. When it is set, the global tracing file is `$XDG_CONFIG_HOME/opencode/braintrust.json` instead of `~/.config/opencode/braintrust.json`.
  </Accordion>

  <Accordion title="Traces use unexpected settings">
    Invocation settings supplied by `bt trace run` take precedence over the saved tracing configuration. For normal sessions, project-local `.opencode/braintrust.json` settings override global settings. A project-level `route` object replaces the entire global `route` object, so include its destination and complete authentication settings.

    The plugin does not use `TRACE_TO_BRAINTRUST`, `BRAINTRUST_PROFILE`, `BRAINTRUST_ORG_NAME`, `BRAINTRUST_PROJECT`, or `BRAINTRUST_ADDITIONAL_METADATA` from the agent's environment to override the saved tracing settings.

    If an older file still has top-level `additional_metadata`, migrate it to `route.additional_metadata` and remove the old key so it cannot override your intended metadata.

    For environment variables accepted by the `bt` commands themselves, see [`bt trace`](/docs/reference/cli/trace).
  </Accordion>
</AccordionGroup>

## Connect to Braintrust MCP

The Braintrust MCP server lets OpenCode query and update Braintrust data. MCP is configured independently from the tracing plugin and its built-in tools.

### Set up the MCP server

<Steps>
  <Step title="Install OpenCode">
    If you haven't already, install [OpenCode](https://opencode.ai/).
  </Step>

  <Step title="Add the Braintrust MCP server">
    Add the Braintrust MCP server to your [OpenCode configuration file](https://opencode.ai/docs/config/), preserving any existing settings and servers:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "braintrust": {
          "type": "remote",
          "url": "https://api.braintrust.dev/mcp"
        }
      }
    }
    ```

    See [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
  </Step>

  <Step title="Authenticate">
    Start OAuth authentication from the terminal:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    opencode mcp auth braintrust
    ```

    Complete the sign-in in your browser. See [OpenCode's MCP authentication documentation](https://opencode.ai/docs/mcp-servers/#authenticating) for details.

    MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
  </Step>

  <Step title="Verify the connection">
    Run `opencode mcp list` to check the connection. Restart OpenCode, then ask it to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
  </Step>
</Steps>

### Use MCP tools

Once connected, OpenCode can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:

* "Show me my recent Braintrust experiments."
* "Query the last 10 logged requests with errors."
* "Compare accuracy scores between my two latest experiments."

See [what the Braintrust MCP can do](/docs/integrations/developer-tools/mcp#what-the-mcp-can-do) for more workflows and example prompts.

### Troubleshooting MCP

<AccordionGroup>
  <Accordion title="Braintrust MCP tools do not appear">
    Confirm that the Braintrust remote server is registered in your OpenCode configuration. Restart OpenCode after adding or changing the server.
  </Accordion>

  <Accordion title="MCP authentication or connection fails">
    Run `opencode mcp auth braintrust` to retry OAuth authentication. If you previously configured API-key authentication, remove the `Authorization` header and any `oauth: false` setting from the Braintrust server's entry in your OpenCode configuration before switching to OAuth.

    For connection and OAuth diagnostics, use `opencode mcp debug braintrust`. See [OpenCode's MCP documentation](https://opencode.ai/docs/mcp-servers/#authenticating).

    For authentication methods, regional and self-hosted endpoints, and network requirements, see the [Braintrust MCP guide](/docs/integrations/developer-tools/mcp#connect-your-client).
  </Accordion>
</AccordionGroup>

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](/docs/evaluate/run-evaluations).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](/docs/integrations/developer-tools/mcp#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).