> ## 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](/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:

* **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, hostname, and Git repository metadata (`git_branch`, `git_commit_sha`, `git_origin_url`)
* **Turn spans**: Record each user-assistant exchange, including skills loaded with the `/skills` command (`loaded_skill_names`, `loaded_skills`)
* **Tool spans**: Log individual tool executions, including skill loads as `skill: <name>` spans with `tool_kind` and `skill_name` metadata

To view your traces, go to your project (default: `opencode`) and select [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs).

#### Data access tools

The plugin provides OpenCode with built-in tools to access your Braintrust data. To trace sessions without exposing these tools to the AI, set `enable_tools` to `false` (see [Configuration](#configuration)).

* **`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                                                                                                                                                                                                                                                       |
| `enable_tools`        | `BRAINTRUST_OPENCODE_ENABLE_TOOLS` | boolean | `true`                         | Register Braintrust-branded data access tools in OpenCode. Set to `false` to keep tracing active without making the tools available to the AI.                                                                                                                                  |
| `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](/docs/admin/organizations#data-plane-region). US: `https://api.braintrust.dev`, EU: `https://api-eu.braintrust.dev`. [Self-hosted](/docs/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](/docs/integrations/developer-tools/mcp#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](/docs/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.