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

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.

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

* **Tracing plugin**: Automatically trace OpenCode sessions and access Braintrust data through built-in tools.
* **MCP server**: Manually configure OpenCode to access Braintrust data through the MCP server.

## Tracing plugin

The `@braintrust/trace-opencode` plugin provides automatic tracing and data access tools for OpenCode.

### Setup

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

  <Step title="Install the plugin">
    Add the Braintrust plugin to your [OpenCode configuration file](https://opencode.ai/docs/config/):

    ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    {
      "plugin": ["@braintrust/trace-opencode"]
    }
    ```
  </Step>

  <Step title="Set your API key">
    The plugin reads your API key from the `BRAINTRUST_API_KEY` environment variable. Set this along with `TRACE_TO_BRAINTRUST` to enable tracing:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    export BRAINTRUST_API_KEY="your-api-key-here"
    export TRACE_TO_BRAINTRUST="true"
    ```

    Then restart your terminal.
  </Step>

  <Step title="Restart OpenCode">
    Close and reopen OpenCode to load the plugin.
  </Step>
</Steps>

### Usage

Once the plugin is installed and configured, automatic tracing and data access tools are enabled when OpenCode starts.

#### Automatic tracing

OpenCode sessions are automatically traced to your Braintrust project (default: `opencode`). Each session includes:

* **Session spans**: Capture workspace and hostname metadata
* **Turn spans**: Record each user-assistant exchange
* **Tool spans**: Log individual tool executions

View your traces at: `https://www.braintrust.dev/app/projects/opencode/logs`

#### Data access tools

The plugin provides OpenCode with built-in tools to access your Braintrust data:

* **`braintrust_query_logs`**: Execute SQL queries against Braintrust logs
* **`braintrust_list_projects`**: View organization projects
* **`braintrust_log_data`**: Manually log evaluation data
* **`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"

### Configuration

You can customize the plugin behavior by creating a `braintrust.json` file at `.opencode/braintrust.json` (project-level) or `~/.config/opencode/braintrust.json` (global):

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "trace_to_braintrust": true,
  "project": "opencode",
  "debug": false,
  "api_key": "your-api-key-here",
  "api_url": "https://api.braintrust.dev",
  "app_url": "https://www.braintrust.dev",
  "org_name": "your-org-name"
}
```

| Setting               | Environment variable  | Type    | Default                        | Description                                                                                                                                                                                                                                                                     |
| --------------------- | --------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trace_to_braintrust` | `TRACE_TO_BRAINTRUST` | boolean | `false`                        | Enable or disable tracing                                                                                                                                                                                                                                                       |
| `project`             | `BRAINTRUST_PROJECT`  | string  | `"opencode"`                   | Project name for traces                                                                                                                                                                                                                                                         |
| `debug`               | `BRAINTRUST_DEBUG`    | boolean | `false`                        | Enable debug logging                                                                                                                                                                                                                                                            |
| `api_key`             | `BRAINTRUST_API_KEY`  | string  | —                              | API key for authentication (required)                                                                                                                                                                                                                                           |
| `api_url`             | `BRAINTRUST_API_URL`  | string  | `"https://api.braintrust.dev"` | API endpoint. Default is based on your organization's [data plane region](/admin/organizations#data-plane-region). US: `https://api.braintrust.dev`, EU: `https://api-eu.braintrust.dev`. [Self-hosted](/admin/self-hosting) deployments must set this to their data plane URL. |
| `app_url`             | `BRAINTRUST_APP_URL`  | string  | `"https://www.braintrust.dev"` | App URL for dashboard access                                                                                                                                                                                                                                                    |
| `org_name`            | `BRAINTRUST_ORG_NAME` | string  | —                              | Organization name (optional)                                                                                                                                                                                                                                                    |

Configuration precedence: defaults → global config → project config → environment variables.

## MCP server

You can also manually configure OpenCode to connect to the Braintrust MCP server for data access.

### Setup

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

### Usage

Once configured, OpenCode can access your Braintrust data through the MCP server. See [MCP documentation](/integrations/developer-tools/mcp#available-tools) for the full list of available tools.

## Troubleshooting

<Accordion title="BRAINTRUST_API_KEY is not set">
  * Verify the variable is set: `echo $BRAINTRUST_API_KEY` (macOS/Linux) or `echo %BRAINTRUST_API_KEY%` (Windows).
  * OpenCode must be **restarted** after setting environment variables.
</Accordion>

<Accordion title="Traces not appearing">
  * Verify `TRACE_TO_BRAINTRUST` is set to `true`.
  * Ensure your API key is correct.
  * Enable debug mode: `export BRAINTRUST_DEBUG=true` and check the logs.
</Accordion>

<Accordion title="Plugin doesn't seem to work">
  * Verify the plugin is listed in your OpenCode configuration file.
  * Check the [OpenCode config documentation](https://opencode.ai/docs/config/) for config file locations.
  * Ensure you're running a recent version of OpenCode that supports plugins.
</Accordion>

<Accordion title="MCP server not appearing">
  * Verify the JSON syntax in your OpenCode configuration file.
  * Ensure the URL is exactly `https://api.braintrust.dev/mcp` (no trailing slash).
  * Restart OpenCode after configuration changes.
</Accordion>

<Accordion title="MCP authentication failures">
  * 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

* **Run evaluations**: Check out the [evaluation guide](/evaluate/run-evaluations) to learn evaluation patterns.
* **Browse the source**: The [braintrust-opencode-plugin repository](https://github.com/braintrustdata/braintrust-opencode-plugin) contains the plugin source code.