Codex

Codex is OpenAI’s command-line AI coding assistant. You can integrate Codex with Braintrust in two ways:

Trace Codex sessions: Log your Codex sessions to Braintrust, including session, turn, model call, and tool spans.
Connect to the Braintrust MCP server: Let Codex access your Braintrust projects, experiments, logs, and other data during a session.

Trace Codex sessions

The trace-codex plugin traces your Codex CLI sessions to Braintrust by observing Codex, not by proxying it:

Codex talks to its model provider directly.
Lifecycle hooks notify the plugin when sessions start, turns run, tools execute, and sessions finish.
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, Codex keeps working. However, you won’t see traces until the setup is fixed.

Each Codex session appears in Braintrust as one trace with session, turn, model call, tool, subagent, and compaction spans. See What gets traced for details.

Set up tracing

Upgrading from trace-codex before v1.0.1? See Upgrade.

Install Codex

If you haven’t already, install Codex.

Install bt and authenticate

Tracing runs through bt, so 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 codex --project my-project   # Replace with your project name

This command:

Adds the Braintrust plugin marketplace.
Installs trace-codex through Codex’s plugin manager.
Selects a project.
Enables tracing.

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

Approve the plugin's hooks

To load the plugin, restart Codex.Then run /hooks in Codex and trust the Braintrust hook definition. Codex does not run plugin hooks until you trust them.

Log a test trace

Start a short Codex session and ask it to do something simple:

codex "Say hello from a traced Codex session"

When the session finishes, open your Braintrust project and check that the trace appears in Logs.

What gets traced

Codex traces in Braintrust include:

Session spans with the working directory, model, permission mode, and Git repository metadata.
Turn spans with prompts and final responses.
Model call spans with conversation input, response output, and token metrics.
Tool spans with inputs, outputs, permission requests, and skill loads.
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.

Settings

bt trace setup codex saves your tracing configuration to ~/.codex/braintrust.json. These saved settings control where traces go during normal Codex sessions.

Setting	Saved key	How to change it
Enable tracing	`trace_to_braintrust`	Set `trace_to_braintrust` to `true` or `false` in `~/.codex/braintrust.json`. Re-running `bt trace setup codex` also re-enables tracing.
Project	`route.destination`	Re-run `bt trace setup codex` with `--project`.
`bt` profile	`route.auth.profile`	Re-run `bt trace setup codex` with `--profile` (the profile must already be logged in with `bt login`).
Organization	`route.auth.org_name`	Re-run `bt trace setup codex` with `--org`.
Extra span metadata	`route.additional_metadata`	To add metadata to every span, edit `route.additional_metadata` in `~/.codex/braintrust.json`.

Notes:

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.

To switch projects, re-run setup:

bt trace setup codex --project another-project

Common workflows

Use custom settings for one run

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

bt trace run --project scratch-project codex "summarize this repo"

This command can send one run to a different project, profile, or organization without changing the saved settings in ~/.codex/braintrust.json.For a non-interactive run, pass Codex’s exec subcommand after --:

bt trace run --project scratch-project codex -- exec "summarize this repo"

Codex may prompt you to trust the plugin’s hooks. For unattended automation, add --dangerously-bypass-hook-trust to the Codex arguments only when you control and trust every enabled hook.

Trace saved Codex sessions

Codex keeps a transcript of every session on disk, so you can send a past session to Braintrust and get its trace after the fact. This works even if tracing wasn’t set up when the session ran:

bt trace import codex <session-id>

To attach the imported session below an existing Braintrust span, pass --parent with the exported span string returned by span.export(). See bt trace import for details, including following a live session with --attach.

Resume a Codex session

When you resume a Codex session, the trace continues in the same root span. Span identities derive from the session ID, so later turns attach to the original trace even after the background tracing process has restarted.

Upgrade

To update bt and trace-codex, follow these steps. If you are upgrading from trace-codex before v1.0.1, the steps also cover the required migration.

Update bt

Update bt before updating trace-codex.

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.1, trace-codex 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 Codex traces. This installs or updates trace-codex and writes the latest tracing settings.

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

Before v1.0.1, the plugin read the destination project from the BRAINTRUST_PROJECT environment variable or the project key in ~/.codex/plugins/data/trace-codex-braintrust-codex-plugins/config.json. If you are upgrading from one of these versions, find the old value. In the command above, replace my-project with that value. If you did not set a project, use codex, the old default. bt trace setup does not migrate this value automatically.

Migrate settings from a plugin version before v1.0.1

If you are upgrading from a plugin version before v1.0.1, use this table to migrate environment variables and settings in ~/.codex/plugins/data/trace-codex-braintrust-codex-plugins/config.json:

Before v1.0.1	Starting in v1.0.1
`BRAINTRUST_API_KEY`	Authentication happens through `bt`. Use `bt login`, or continue using `BRAINTRUST_API_KEY`.
`TRACE_TO_BRAINTRUST=true`	Run `bt trace setup codex`, which saves `trace_to_braintrust: true` in `~/.codex/braintrust.json`, then remove the variable.
`BRAINTRUST_PROJECT` or the `project` key in `~/.codex/plugins/data/trace-codex-braintrust-codex-plugins/config.json`	Pass its value to `bt trace setup codex --project <name>`, which saves `route.destination` in `~/.codex/braintrust.json`, then remove the old variable or key.
`CODEX_PARENT_SPAN_ID`, `CODEX_ROOT_SPAN_ID`	Remove these variables. They no longer attach a running Codex session below another Braintrust span. To attach a finished session below an existing span, run `bt trace import codex <session-id> --parent <exported-span>` with the exported span string returned by `span.export()`.
`BRAINTRUST_FLUSH_ON_TURN_END`, `BRAINTRUST_ENVIRONMENT_TYPE`, `BRAINTRUST_ENVIRONMENT_NAME`	Remove these variables. The plugin no longer reads them.

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

Troubleshooting

Traces do not appear

Check the following, in order:

Confirm the plugin is installed and enabled: run codex plugin list --marketplace braintrust-codex-plugins and check that trace-codex appears with installed, enabled.
Restart Codex after setup so it loads the plugin.
Check that you reviewed and trusted the plugin’s hooks when Codex prompted you. For non-interactive runs, pass --dangerously-bypass-hook-trust (but only when you control and trust every enabled hook).
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 tracing is enabled: re-run bt trace setup codex to set trace_to_braintrust to true.
After running a session, check the background process: bt trace status shows whether the tracing daemon is running and which sessions it knows about.

Tracing failures don’t interrupt Codex, so your Codex session can keep working even when traces do not appear.

Connect to the Braintrust MCP server

Codex can use Braintrust’s MCP server to access your projects, experiments, and logs.

Set up the MCP server

Install Codex

If you haven’t already, install Codex.

Set your API key

Set the BRAINTRUST_API_KEY environment variable with your API key:

export BRAINTRUST_API_KEY="your-api-key-here"

Add the Braintrust MCP server

Edit ~/.codex/config.toml and add the Braintrust MCP server configuration:

[mcp_servers.braintrust]
url = "https://api.braintrust.dev/mcp"
bearer_token_env_var = "BRAINTRUST_API_KEY"

This configures Codex to read your Braintrust API key from the BRAINTRUST_API_KEY environment variable.

Verify the setup

Launch Codex with the environment variable set:

codex

Run the /mcp command to verify Braintrust is installed and accessible.

Use MCP tools

Once configured, Codex 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 Codex:

“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

Braintrust MCP tools do not appear

Verify the TOML configuration syntax is correct.
Check that the file path is exactly ~/.codex/config.toml.
Run /mcp in Codex to see available MCP servers.
Try restarting Codex.

MCP authentication fails

Verify your API key is correct (no extra spaces).
Ensure you can log into Braintrust using the account associated with the API key.
Generate a new API key if needed.

MCP connection errors

Verify the URL is exactly https://api.braintrust.dev/mcp (no trailing slash).
Check your internet connection.
Corporate networks may need to allowlist api.braintrust.dev and *.braintrust.dev.

Next steps

Learn the CLI: See the full bt trace reference, including session imports 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.
Query with SQL: Learn how to query with SQL for complex data analysis.
Browse the plugin: See the Codex plugin repository for releases and distribution files. The shared coding-agent plugins repository contains the source for all Braintrust coding-agent plugins.

AI providers

SDKs

Developer tools

Runtime environments

Trace Codex sessions

Set up tracing

What gets traced

Settings

Common workflows

Upgrade

Troubleshooting

Connect to the Braintrust MCP server

Set up the MCP server

Use MCP tools

Troubleshooting

Next steps

​Trace Codex sessions

​Set up tracing

​What gets traced

​Settings

​Common workflows

​Upgrade

​Troubleshooting

​Connect to the Braintrust MCP server

​Set up the MCP server

​Use MCP tools

​Troubleshooting

​Next steps

Trace Codex sessions

Set up tracing

What gets traced

Settings

Common workflows

Upgrade

Troubleshooting

Connect to the Braintrust MCP server

Set up the MCP server

Use MCP tools

Troubleshooting

Next steps