> ## 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 with the trace-opencode plugin and access Braintrust data through built-in tools or MCP

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.

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

* **Trace OpenCode sessions**: Log OpenCode sessions to Braintrust. The same plugin can also register built-in Braintrust tools that call `bt`.
* **Connect to the Braintrust MCP server**: Configure OpenCode's MCP client for Braintrust data access. This is separate from the plugin's built-in tools.

## Trace OpenCode sessions

The [`@braintrust/trace-opencode`](https://www.npmjs.com/package/@braintrust/trace-opencode) plugin traces OpenCode sessions to Braintrust by observing OpenCode, not by proxying it:

* OpenCode talks to its model provider directly.
* Native events notify the plugin when sessions start, turns run, models respond, and tools execute.
* 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, OpenCode keeps working. However, you won't see traces until the setup is fixed.

Each OpenCode session appears in Braintrust as one trace with session, turn, model call, and tool spans. See [What gets traced](#what-gets-traced) for details.

### Set up tracing

<Note>
  Upgrading from `@braintrust/trace-opencode` before v1.0.0? See [Upgrade](#upgrade).
</Note>

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

  <Step title="Install bt and authenticate">
    Tracing runs through `bt`, and the OpenCode plugin does not install it for you. [Install the CLI](/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:

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

    This command:

    * Adds `@braintrust/trace-opencode@^1` to your [OpenCode configuration file](https://opencode.ai/docs/config/).
    * 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 OpenCode">
    Restart OpenCode so it loads the plugin and tracing settings.
  </Step>

  <Step title="Log a test trace">
    Start a short OpenCode 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

OpenCode traces in Braintrust include:

* Session spans with `session_id`, `source`, Git repository metadata, and parent session fields for subagents.
* Turn spans with prompts, model names, and `loaded_skill_names` when the prompt requests skills.
* Model call spans with conversation input, response output, errors, and token metrics.
* Tool spans with tool inputs and outputs. When OpenCode runs the `skill` tool, the span is named `skill: <name>`.
* Subagent session spans nested under their parent session.

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

### Settings

[`bt trace setup opencode`](/docs/reference/cli/trace#bt-trace-setup) saves your tracing configuration to `~/.config/opencode/braintrust.json`. These saved settings control where traces go during normal OpenCode sessions.

| Setting                   | Saved key                   | How to change it                                                                                                                                                                                                             |
| ------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable tracing            | `trace_to_braintrust`       | Set `trace_to_braintrust` to `true` or `false` in the config file. Re-running `bt trace setup opencode` also re-enables tracing. Env var `TRACE_TO_BRAINTRUST` overrides the saved value.                                    |
| Project                   | `route.destination`         | Re-run `bt trace setup opencode` with `--project`. Env var `BRAINTRUST_PROJECT` overrides the saved value.                                                                                                                   |
| `bt` profile              | `route.auth.profile`        | Re-run `bt trace setup opencode` with `--profile` (the profile must already be logged in with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context)). Env var `BRAINTRUST_PROFILE` overrides the saved value. |
| Organization              | `route.auth.org_name`       | Re-run `bt trace setup opencode` with `--org`. Env var `BRAINTRUST_ORG_NAME` overrides the saved value.                                                                                                                      |
| Extra span metadata       | `route.additional_metadata` | Edit `route.additional_metadata` in the config file to save metadata. Env var `BRAINTRUST_ADDITIONAL_METADATA` overrides the saved value.                                                                                    |
| Built-in Braintrust tools | `enable_tools`              | Set `enable_tools` to `true` or `false` in the config file. On by default. Env var `BRAINTRUST_OPENCODE_ENABLE_TOOLS` overrides the saved value. See [Built-in Braintrust tools](#built-in-braintrust-tools).                |
| Debug logging             | `debug`                     | Set `debug` to `true` in the config file. Env var `BRAINTRUST_DEBUG` overrides the saved value.                                                                                                                              |

Notes:

* For OpenCode tracing, environment variables override saved settings. The project config (`.opencode/braintrust.json`) overrides the global config (`~/.config/opencode/braintrust.json`).
* 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 apply custom settings to a single OpenCode run, launch OpenCode 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 opencode -- run "summarize the changes in this repo"
  ```

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

### Built-in Braintrust tools

In addition to tracing sessions, `@braintrust/trace-opencode` can register built-in Braintrust tools in OpenCode. These tools let OpenCode query Braintrust data through `bt` during a session, without a separate MCP server configuration.

The plugin registers the tools by default (`enable_tools` is `true`). `bt` owns authentication and API access. To trace sessions without giving OpenCode access to these tools, set `enable_tools` to `false`.

* `braintrust_query_logs` - Execute SQL queries against Braintrust logs.
* `braintrust_list_projects` - View organization projects.
* `braintrust_get_experiments` - Access recent experiments.

Example prompts you can use in OpenCode:

* "Can you show me the last 10 logs from Braintrust?"
* "List my Braintrust projects"
* "Query logs where `scores.Factuality < 0.5`"
* "Show me my recent experiments"

### Upgrade

To get the latest `bt` and `@braintrust/trace-opencode`, follow these steps. If you are upgrading from `@braintrust/trace-opencode` before v1.0.0, the steps also cover the required migration.

<Steps>
  <Step title="Update bt">
    Update `bt` before updating `@braintrust/trace-opencode`.

    <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 v1.0.0, `@braintrust/trace-opencode` 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 OpenCode traces. This updates OpenCode's plugin pin and writes the latest tracing settings.

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

    <Note>
      Before v1.0.0, the plugin read the destination project from the top-level `project` key in `~/.config/opencode/braintrust.json` or your project's `.opencode/braintrust.json`. If you are upgrading from one of these versions, find the old value. In the command above, replace `my-project` with that value. `bt trace setup` does not migrate this value automatically.
    </Note>
  </Step>

  <Step title="Migrate settings from a plugin version before v1.0.0">
    If you are upgrading from a plugin version before v1.0.0, use this table to migrate environment variables and settings from `~/.config/opencode/braintrust.json` or your project's `.opencode/braintrust.json`:

    | Before v1.0.0                                                                                                     | Starting in v1.0.0                                                                                                                                                                                                         |
    | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `BRAINTRUST_API_KEY`                                                                                              | Authentication happens through `bt`. Use [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context), or continue using `BRAINTRUST_API_KEY`.                                                                     |
    | `api_key`, `api_url`, `app_url` in `~/.config/opencode/braintrust.json` or `.opencode/braintrust.json`            | Remove these keys. The plugin no longer reads them.                                                                                                                                                                        |
    | Top-level `project`, `profile`, `org_name` in `~/.config/opencode/braintrust.json` or `.opencode/braintrust.json` | Pass their values to `bt trace setup opencode` with `--project`, `--profile`, and `--org` as needed, then remove the old top-level keys. Setup saves the new values under `route` in `~/.config/opencode/braintrust.json`. |
  </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:

  * Verify `bt` is installed and current: `bt --version` (v0.16.0 or later).
  * Verify `bt` is authenticated: run `bt status`. Authenticate with [`bt login`](/docs/reference/cli/quickstart#authenticate-and-set-context) or `BRAINTRUST_API_KEY`.
  * Verify the plugin is listed in your OpenCode configuration file.
  * Verify tracing is enabled: in `~/.config/opencode/braintrust.json` and any project-level `.opencode/braintrust.json`, confirm that `trace_to_braintrust` is `true` and `route.destination` names the intended project.
  * Restart OpenCode after any configuration change.
  * Enable debug mode with `BRAINTRUST_DEBUG=true` and check the OpenCode logs.

  Tracing failures don't interrupt OpenCode, so your OpenCode session can keep working even when traces do not appear.
</Accordion>

<Accordion title="Plugin does not load">
  * Check the [OpenCode config documentation](https://opencode.ai/docs/config/) for config file locations.
  * Confirm the `plugin` field is an array and includes `@braintrust/trace-opencode@^1`.
  * Restart OpenCode after changing configuration.
</Accordion>

## Connect to the Braintrust MCP server

OpenCode can use Braintrust's MCP server to access your projects, experiments, and logs. This is separate from the plugin's 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">
    Edit your [OpenCode configuration file](https://opencode.ai/docs/config/) and add the Braintrust MCP server:

    ```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",
          "headers": {
            "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
          }
        }
      }
    }
    ```

    Replace `YOUR_BRAINTRUST_API_KEY` with your actual API key.
  </Step>

  <Step title="Restart OpenCode">
    Restart OpenCode to apply the configuration changes.
  </Step>
</Steps>

<Note>
  The example uses `https://api.braintrust.dev/mcp` (US data plane). If your organization is on the [EU data plane](/docs/admin/organizations#data-plane-region), use `https://api-eu.braintrust.dev/mcp`.
</Note>

### Use MCP tools

Once configured, OpenCode can access Braintrust data through the MCP server. You can fetch experiment results, query logs, log data, and more. See [MCP documentation](/docs/integrations/developer-tools/mcp#tools) for details.

Example prompts in OpenCode:

* "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="MCP server does not appear">
  * Verify the JSON syntax in your OpenCode configuration file.
  * Verify the URL is `https://api.braintrust.dev/mcp` or `https://api-eu.braintrust.dev/mcp`, with no trailing slash.
  * Restart OpenCode after configuration changes.
</Accordion>

<Accordion title="MCP authentication fails">
  * Verify your API key is correct and has access to Braintrust.
  * Check the authorization header format: `"Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"`.
</Accordion>

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace), including setup 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.