Skip to main content
OpenCode 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 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, independently of MCP.

​
Set up tracing

If @braintrust/trace-opencode is already installed, follow Update the tracing plugin.
1

Install OpenCode

If you haven’t already, install OpenCode. The plugin requires OpenCode v1.2.25 or later.
2

Install and authenticate bt

Follow the bt CLI quickstart to install bt v0.19.3 or later, authenticate, and set your active context.
3

Enable tracing

Before starting OpenCode, run this command in a terminal:
This command:
  • Adds or updates @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.
4

Restart OpenCode

Restart OpenCode so it loads the plugin and tracing settings.
5

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

​
What Braintrust traces

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

Use 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 with the corresponding options. Running bt 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.
Use bt trace disable opencode 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.

​
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:
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.
1

Update bt

Follow the CLI migration guide to update bt to the latest version and complete the applicable migrations.
2

Update the tracing plugin

bt trace update updates the plugin’s package specification in the global OpenCode configuration without changing your saved tracing configuration.
3

Restart and verify OpenCode

Restart OpenCode, run a short session, and confirm that its trace appears on the Logs page in the intended Braintrust project.

​
Migrate from an older plugin version

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

Inspect your OpenCode plugins

Inspect your active OpenCode configuration and find @braintrust/trace-opencode in the plugin list:
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.
If the plugin is not installed, follow Set up tracing. If you cannot determine the installed version from its configured version range, complete both migration sections below.
2

Install or update bt

These steps require bt v0.19.3 or later. Check whether bt is installed:
3

Complete version-specific migration steps

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.
Complete this section if you started your migration from a plugin version earlier than v1.0.0.
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. Keep credentials private and retain any settings needed by other integrations.
Complete this section if you started your migration from a plugin version earlier than v2.0.0.
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.
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.
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.
4

Apply your tracing settings

Run this command with your intended project, using the project you recorded earlier to preserve your destination:
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.
5

Restart and verify OpenCode

Restart OpenCode, run a short session, and confirm that its trace appears on the Logs page in the intended Braintrust project. Check each project where you changed local tracing settings.
6

Remove obsolete settings

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

​
Troubleshooting tracing

First, run bt trace doctor opencode. Then, review the following:
Run opencode debug config and confirm that @braintrust/trace-opencode@^2 is in the plugin list. If it is missing or broken, run:
Restart OpenCode afterward.
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.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting and the CLI migration troubleshooting guide.Tracing failures do not interrupt the OpenCode session.
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.
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.

​
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

1

Install OpenCode

If you haven’t already, install OpenCode.
2

Add the Braintrust MCP server

Add the Braintrust MCP server to your OpenCode configuration file, preserving any existing settings and servers:
See Endpoints for EU and self-hosted URLs.
3

Authenticate

Start OAuth authentication from the terminal:
Complete the sign-in in your browser. See OpenCode’s MCP authentication documentation for details.MCP authentication is separate from bt login, which authenticates the CLI and tracing integration.
4

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.

​
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 for more workflows and example prompts.

​
Troubleshooting MCP

Confirm that the Braintrust remote server is registered in your OpenCode configuration. Restart OpenCode after adding or changing the server.
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.For authentication methods, regional and self-hosted endpoints, and network requirements, see the Braintrust MCP guide.

​
Next steps