OpenCode

OpenCode 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 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 to build and send traces to Braintrust.
Authentication happens through bt 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 for details.

Set up tracing

Upgrading from @braintrust/trace-opencode before v1.0.0? See Upgrade.

Install OpenCode

If you haven’t already, install OpenCode.

Install bt and authenticate

Tracing runs through bt, and the OpenCode plugin does not install it for you. Install the CLI and authenticate:

curl -fsSL https://bt.dev/cli/install.sh | bash
bt login

You can also install with mise or npm, or with PowerShell on Windows.

Configure the plugin

After bt is installed and authenticated, run the following command:

bt trace setup opencode --project my-project   # Replace with your project name

This command:

Adds @braintrust/trace-opencode@^1 to your OpenCode configuration file.
Selects a project.
Enables tracing.

To learn what this command writes and how to change it later, see Settings.

Restart OpenCode

Restart OpenCode so it loads the plugin and tracing settings.

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.

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 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`). 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.
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 or BRAINTRUST_API_KEY. See credential precedence.
To use different settings for one launched session without changing saved configuration, use bt trace run.

Common workflows

Use custom settings for one run

To apply custom settings to a single OpenCode run, launch OpenCode with bt trace run:

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.

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.

Update bt

Update bt before updating @braintrust/trace-opencode.

If you’re also migrating from an older bt version with bt auth commands, review the CLI migration guide. It explains how saved logins carry over, how profiles and organizations changed, and which commands replaced the old auth commands.

bt update

bt update updates installs made with the standalone shell or PowerShell installer. If you installed with mise or 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.

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. You can also authenticate with BRAINTRUST_API_KEY.

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.

bt trace setup opencode --project my-project   # Replace with your project name

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.

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`, 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`.

For current settings and how to change them, see Settings.

Troubleshooting

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

Plugin does not load

Check the OpenCode config documentation for config file locations.
Confirm the plugin field is an array and includes @braintrust/trace-opencode@^1.
Restart OpenCode after changing configuration.

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

Install OpenCode

If you haven’t already, install OpenCode.

Add the Braintrust MCP server

Edit your OpenCode configuration file and add the Braintrust MCP server:

{
  "$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.

Restart OpenCode

Restart OpenCode to apply the configuration changes.

The example uses https://api.braintrust.dev/mcp (US data plane). If your organization is on the EU data plane, use https://api-eu.braintrust.dev/mcp.

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

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.

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

Next steps

Learn the CLI: See the full bt trace reference, including setup and per-run tracing.
Run evaluations: Check out the evaluation guide to learn evaluation patterns.
Explore MCP tools: See the MCP documentation for all available commands.
Browse the source: The coding-agent plugins repository contains the plugin source code.

AI providers

SDKs

Developer tools

Runtime environments

Trace OpenCode sessions

Set up tracing

What gets traced

Settings

Common workflows

Built-in Braintrust tools

Upgrade

Troubleshooting

Connect to the Braintrust MCP server

Set up the MCP server

Use MCP tools

Troubleshooting

Next steps

​Trace OpenCode sessions

​Set up tracing

​What gets traced

​Settings

​Common workflows

​Built-in Braintrust tools

​Upgrade

​Troubleshooting

​Connect to the Braintrust MCP server

​Set up the MCP server

​Use MCP tools

​Troubleshooting

​Next steps

Trace OpenCode sessions

Set up tracing

What gets traced

Settings

Common workflows

Built-in Braintrust tools

Upgrade

Troubleshooting

Connect to the Braintrust MCP server

Set up the MCP server

Use MCP tools

Troubleshooting

Next steps