Skip to main content
Codex is OpenAI’s coding agent. You can connect it to Braintrust in two ways:
  • Trace Codex 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 Codex.

​
Trace Codex sessions

The trace-codex plugin uses bt to trace your Codex sessions to Braintrust.

​
Set up tracing

If trace-codex is already installed, follow Update the tracing plugin.
1

Install Codex

If you haven’t already, install the Codex CLI.
2

Install and authenticate bt

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

Enable tracing

Before starting Codex, run this command in a terminal:
This command:
  • Adds or refreshes the Braintrust plugin marketplace.
  • Installs (or updates) and enables trace-codex.
  • Writes ~/.codex/braintrust.json, which records whether tracing is enabled and which project receives traces.
  • With bt v0.27.2 or later, trusts the Braintrust hooks in Codex, so you don’t need to approve them through /hooks. This step runs the codex command, so the Codex CLI must be on your PATH.
The tracing file stores settings, not credentials. These settings apply across projects during normal sessions.For more information, see bt trace enable.
4

Restart Codex

Restart Codex so it loads the plugin.With bt earlier than v0.27.2, also run /hooks and trust the Braintrust hook definition. Codex does not run plugin hooks until you trust them.
5

Log a test trace

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

Codex traces in Braintrust include:
  • Session spans with the working directory, model, permission mode, Git repository metadata, and the final response of the last completed turn.
  • Turn spans with prompts, including attached images, and final responses. When you interrupt a turn, the turn and the model call and tool spans still open record metadata.outcome as interrupted and metadata.termination_reason instead of an error.
  • Model call spans reconstructed from the session transcript, with conversation input, response output, and available token metrics. Images in prompts and tool results stay images in the conversation input.
  • Tool spans with inputs, outputs, permission requests, and skill loads. When a tool call runs shell commands, a command that exits with a nonzero code records an error on the tool span, such as Command exited with code 1, even if the tool call as a whole completes. The span records each command’s result in metadata.command_outcomes.
  • Subagent spans nested under the turn that started the subagent.
  • Compaction spans for context compactions, with a nested model span for the compaction call.
Every span records its origin as braintrust.plugin.codex, along with versions in context.span_origin: the plugin version in version, the bt version in bt.version, and the Codex version in codex.version. These versions are captured when each span is created, and unknown versions are null. Each turn span and every span under it, including subagent spans, records the turn’s span ID in metadata.turn_span_id.

​
Common workflows

Use bt trace run to trace a single Codex invocation without changing the saved tracing configuration.This workflow launches Codex from the terminal.To change the saved destination, profile, or organization, rerun bt trace enable codex 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.
Codex stores session transcripts locally. Use bt trace import to import a past session, even if tracing was not enabled when it ran. With bt v0.28.0 or later, this includes sessions whose transcripts Codex has compressed into .jsonl.zst files. You can’t follow a compressed session with --attach.You can also attach an imported session to an existing span or experiment.
When you resume a Codex session, new turns are added to its existing Braintrust trace.
Use bt trace disable codex to uninstall the tracing plugin and remove its tracing configuration. Saved bt profiles and credentials are preserved. Restart Codex afterward.

​
Update the tracing plugin

To update the plugin, follow these steps:
If codex plugin list --json shows trace-codex earlier than v1.0.1, or bt --version shows a version earlier than v0.19.0, 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 installed plugin without changing your saved tracing configuration.
3

Restart and verify Codex

Restart Codex. With bt earlier than v0.27.2, also trust the updated Braintrust hook through /hooks if prompted. 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 trace-codex plugin, follow these steps:
1

Inspect your Codex plugins

Run this command and find trace-codex@braintrust-codex-plugins:
Record the tracing plugin’s starting version before updating. If your tracing configuration file exists, also record its profile, organization, project, and any custom tracing settings you want to preserve.
If the tracing plugin is not installed, follow Set up tracing.
2

Install or update bt

Check whether bt is installed:
3

Complete version-specific migration steps

Complete each section for a version newer than your starting trace-codex version, beginning with the oldest. If no sections apply, continue to the next step.
Complete this section if you started your migration from a tracing-plugin version earlier than v1.0.1.
Before v1.0.1, the tracing plugin read settings from its own config.json and environment variables. Starting in v1.0.1, it reads a dedicated configuration file written by bt trace enable codex, and bt handles authentication.Find the project that received your traces before updating. In v1.0.0, the settings take precedence in this order:
  1. project in ~/.codex/plugins/data/trace-codex-braintrust-codex-plugins/config.json.
  2. BRAINTRUST_PROJECT in your shell environment.
  3. BRAINTRUST_DEFAULT_PROJECT in your shell environment.
  4. The default project, codex.
In v0.1.0 and earlier, environment variables took precedence over the file instead. If both were set, use the project that actually received your traces.If you configured a different plugin data directory with BRAINTRUST_EVENT_SERVER_LOG_DIR, look for config.json there instead.Also record settings you want to preserve:
  • Extra root-span metadata from additionalMetadata in the old file or BRAINTRUST_ADDITIONAL_METADATA.
  • Turn-end flushing from flushOnTurnEnd in the old file or BRAINTRUST_FLUSH_ON_TURN_END.
  • Deployment endpoints from apiUrl and appUrl in the old file, or BRAINTRUST_API_URL and BRAINTRUST_APP_URL. Configure the appropriate deployment when you authenticate with bt.
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.To preserve metadata from an older plugin’s configuration or BRAINTRUST_ADDITIONAL_METADATA, pass it explicitly with --additional-metadata '<JSON>'. Normal-session hooks do not read metadata from this environment variable.The command updates your tracing file, normally ~/.codex/braintrust.json. Check the following settings in that file:
  • Existing route.additional_metadata is preserved unless you pass --additional-metadata.
  • 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.
5

Restart and verify Codex

Restart Codex. With bt earlier than v0.27.2, also trust the updated Braintrust hook through /hooks if prompted. Run a short session and confirm that its trace appears on the Logs page in the intended Braintrust project.
6

Remove obsolete settings

Complete this step only if you started with a tracing-plugin version earlier than v1.0.1 and verified that traces reach the intended project in the previous step.
The tracing plugin now reads its settings from a dedicated configuration file. Environment variables and plugin settings you previously configured for tracing may no longer be needed.Check these locations for leftover settings:
  • Your shell configuration
  • ~/.codex/plugins/data/trace-codex-braintrust-codex-plugins/config.json, or the custom plugin data directory you previously configured
Remove the settings below if they were used only for tracing. Keep any that other bt commands, MCP connections, or integrations still need:To attach an imported session to an existing span or experiment, use bt trace import instead of the old parent-span settings.

​
Troubleshooting tracing

First, run bt trace doctor codex. Then, review the following:
Run codex plugin list --json and confirm that trace-codex@braintrust-codex-plugins is installed and enabled. If it is missing or broken, run:
Restart Codex afterward. With bt earlier than v0.27.2, also trust the Braintrust hook through /hooks.
With bt v0.27.2 or later, bt trace enable codex and bt trace update codex install the plugin, then trust its hooks in Codex. If trusting fails, the command exits with an error that starts with Codex plugin installed, but hook activation failed, and the plugin and tracing settings stay in place. Common causes:
  • Codex hooks are disabled in config: Enable hooks in your Codex configuration, then rerun the command.
  • Installed Braintrust hooks differ from this bt version: Update bt, then rerun the command.
  • Unexpected or disabled Braintrust hook definition: Run /hooks in Codex and check the Braintrust hooks.
The command runs the Codex CLI found on your PATH. If it reports an unknown method or times out, update Codex and retry.
If Codex was running when its plugin or configuration changed, restart it. Confirm that bt is on the PATH of the process that launches Codex, and that the Braintrust hooks are trusted in /hooks.Run bt trace doctor codex and confirm that tracing is enabled and routed to the intended project.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 Codex session.
bt trace run codex rejects --dangerously-bypass-hook-trust because it conflicts with the tracing hook managed by bt. Remove the option from the managed command.If an automation requires the option, run Codex directly with the installed tracing plugin instead. Bypass hook trust only when you control and trust every enabled hook.
The tracing file remains at ~/.codex/braintrust.json even when CODEX_HOME changes Codex’s own configuration directory.An explicit BRAINTRUST_DAEMON_CONFIG (BT_DAEMON_CONFIG in bt v0.25.0 and earlier) override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Codex.
Invocation settings supplied by bt trace run take precedence over the saved tracing configuration. For normal sessions, the integration does not use TRACE_TO_BRAINTRUST, BRAINTRUST_PROJECT, or BRAINTRUST_ADDITIONAL_METADATA from the agent’s environment to override the saved tracing settings.For environment variables accepted by the bt commands themselves, see bt trace.

​
Connect to Braintrust MCP

The Braintrust MCP server lets Codex query and update Braintrust data. MCP is configured independently from the tracing plugin.
Braintrust retired its braintrust MCP plugin for Codex in favor of Codex’s native MCP configuration. If you installed the plugin, remove it before configuring the direct connection.Check whether the plugin is still installed:
If braintrust@braintrust-codex-plugins appears in the installed plugins, remove it:
Keep the marketplace if you use the trace-codex tracing plugin.
1

Choose authentication

Use OAuth when your client supports it. Your client opens a Braintrust authorization page where you sign in and approve access. The server acts with the permissions of the account you sign in with.
  • No Braintrust API key required
  • No OAuth client ID or client secret to configure
The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at /.well-known/oauth-authorization-server on the same host as your MCP endpoint (see next step), so a client can register itself.
Your bt login doesn’t authenticate the MCP server.
2

Choose your endpoint

Use the endpoint for your organization’s data plane region:Other connection details:
  • Self-hosted: Copy the MCP URL from Settings > Data plane. This is your Braintrust API URL with /mcp appended.
  • Transport: If your client asks you to choose a transport, choose HTTP (also called streamable HTTP). SSE-only clients can’t connect.
3

Add the server to Codex

Follow the Codex guide to add the remote server.
4

Verify the connection

To verify the connection, ask Codex to list your recent Braintrust projects. If it can’t connect, see Braintrust MCP troubleshooting.
5

Start using Braintrust tools

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

​
Next steps