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 uses bt to trace your OpenCode sessions to Braintrust. 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: