Skip to main content
OpenCode 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

1

Install OpenCode

If you haven’t already, install OpenCode.
2

Install the plugin

Add the Braintrust plugin to your OpenCode configuration file:
{
  "plugin": ["@braintrust/trace-opencode"]
}
3

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:
export BRAINTRUST_API_KEY="your-api-key-here"
export TRACE_TO_BRAINTRUST="true"
Then restart your terminal.
4

Restart OpenCode

Close and reopen OpenCode to load the plugin.

​
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): 
{
  "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"
}
SettingEnvironment variableTypeDefaultDescription
trace_to_braintrustTRACE_TO_BRAINTRUSTbooleanfalseEnable or disable tracing
projectBRAINTRUST_PROJECTstring"opencode"Project name for traces
debugBRAINTRUST_DEBUGbooleanfalseEnable debug logging
api_keyBRAINTRUST_API_KEYstring—API key for authentication (required)
api_urlBRAINTRUST_API_URLstring"https://api.braintrust.dev"API endpoint (for self-hosted instances)
app_urlBRAINTRUST_APP_URLstring"https://www.braintrust.dev"App URL for dashboard access
org_nameBRAINTRUST_ORG_NAMEstring—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

1

Install OpenCode

If you haven’t already, install OpenCode.
2

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

Restart OpenCode

Restart OpenCode to apply the configuration changes.

​
Usage

Once configured, OpenCode can access your Braintrust data through the MCP server. See MCP documentation for the full list of available tools.

​
Troubleshooting

  • 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.
  • 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.
  • Verify the plugin is listed in your OpenCode configuration file.
  • Check the OpenCode config documentation for config file locations.
  • Ensure you’re running a recent version of OpenCode that supports plugins.
  • 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.
  • Verify your API key is correct and has access to Braintrust.
  • Check the authorization header format: "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY".

​
Next steps