> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Trace Codex sessions to Braintrust and access your Braintrust data through the MCP server

[Codex](https://openai.com/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](https://github.com/braintrustdata/braintrust-codex-plugin) uses `bt` to trace your Codex sessions to Braintrust.

### Set up tracing

> [!NOTE]
>
> If `trace-codex` is already installed, follow [Update the tracing plugin](#update-the-tracing-plugin).

**1. Install Codex**

If you haven't already, install the [Codex CLI](https://learn.chatgpt.com/docs/codex/cli).

**2. Install and authenticate bt**

Follow the [`bt` CLI quickstart](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt`, authenticate, and set your active context.

**3. Enable tracing**

Before starting Codex, run this command in a terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable codex --project <your-project>
```

This command:

* Adds or refreshes the Braintrust plugin marketplace.
* Installs (or updates) and enables [`trace-codex`](https://github.com/braintrustdata/braintrust-codex-plugin).
* 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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable).

**4. Restart Codex**

Restart Codex so it loads the plugin.

With `bt` earlier than v0.27.2, also run [`/hooks`](https://learn.chatgpt.com/docs/hooks#review-and-trust-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\*\*](https://www.braintrust.dev/app/~/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

> [accordion] Use different tracing settings for one session
>
> Use [`bt trace run`](https://docs.braintrust.dev/reference/cli/trace#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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/reference/cli/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](https://docs.braintrust.dev/reference/cli/trace.md#tag-traces).

> [accordion] Trace a saved Codex session
>
> Codex stores session transcripts locally. Use [`bt trace import`](https://docs.braintrust.dev/reference/cli/trace#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.

> [accordion] Resume a Codex session
>
> When you resume a Codex session, new turns are added to its existing Braintrust trace.

> [accordion] Stop tracing Codex sessions
>
> Use [`bt trace disable codex`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-disable) 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:

> [!NOTE]
>
> 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](#migrate-from-an-older-plugin-version).

**1. Update bt**

Follow the [CLI migration guide](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations.

**2. Update the tracing plugin**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update codex
```

[`bt trace update`](https://docs.braintrust.dev/reference/cli/trace#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\*\*](https://www.braintrust.dev/app/~/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`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
codex plugin list --json
```

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.

> [!NOTE]
>
> If the tracing plugin is not installed, follow [Set up tracing](#set-up-tracing).

**2. Install or update bt**

Check whether `bt` is installed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt --version
```

* If the command succeeds, [migrate to the latest version](https://docs.braintrust.dev/reference/cli/migrate.md) (unless you've already done so).
* Otherwise, [install `bt`](https://docs.braintrust.dev/reference/cli/quickstart), authenticate, and set organization and project context.

**3. Complete version-specific migration steps**

> [!NOTE]
>
> 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.

> [accordion] trace-codex v1.0.1
>
> > [!NOTE]
> >
> > 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`](https://docs.braintrust.dev/reference/cli/login).

**4. Apply your tracing settings**

Run this command with your intended project, using the project you recorded earlier to preserve your destination:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable codex --project <your-project>
```

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\*\*](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.

**6. Remove obsolete settings**

> [!NOTE]
>
> 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.

> [accordion] Settings used before trace-codex v1.0.1
>
> 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:
>
> | Old environment variable | Old configuration key |
> | - | - |
> | `TRACE_TO_BRAINTRUST` | `traceToBraintrust` |
> | `BRAINTRUST_PROJECT`, `BRAINTRUST_DEFAULT_PROJECT` | `project` |
> | `BRAINTRUST_API_KEY` | `apiKey` |
> | `BRAINTRUST_API_URL`, `BRAINTRUST_APP_URL` | `apiUrl`, `appUrl` |
> | `BRAINTRUST_ADDITIONAL_METADATA` | `additionalMetadata` |
> | `BRAINTRUST_FLUSH_ON_TURN_END` | `flushOnTurnEnd` |
> | `CODEX_PARENT_SPAN_ID`, `CODEX_ROOT_SPAN_ID` | `parentSpanId`, `rootSpanId` |
> | `BRAINTRUST_ENVIRONMENT_TYPE`, `BRAINTRUST_ENVIRONMENT_NAME` | None |
> | `BRAINTRUST_EVENT_SERVER_RECORD_FILE` | `recordFile` |
> | `BRAINTRUST_EVENT_SERVER_PORT` | `port` |
> | `BRAINTRUST_EVENT_SERVER_IDLE_TIMEOUT_MS` | `idleTimeoutMs` |
> | `BRAINTRUST_EVENT_SERVER_IDLE_CHECK_INTERVAL_MS` | `idleCheckIntervalMs` |
> | `BRAINTRUST_EVENT_SERVER_LOG_DIR` | None |
>
> To attach an imported session to an existing span or experiment, use [`bt trace import`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-import) instead of the old parent-span settings.

### Troubleshooting tracing

First, run `bt trace doctor codex`. Then, review the following:

> [accordion] The tracing plugin is missing or disabled
>
> Run `codex plugin list --json` and confirm that `trace-codex@braintrust-codex-plugins` is installed and enabled. If it is missing or broken, run:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace enable codex --project <your-project>
> ```
>
> Restart Codex afterward. With `bt` earlier than v0.27.2, also trust the Braintrust hook through `/hooks`.

> [accordion] Setup reports that hook activation failed
>
> 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.

> [accordion] Traces do not appear after setup
>
> 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](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](https://docs.braintrust.dev/reference/cli/migrate.md#troubleshooting).
>
> Tracing failures do not interrupt the Codex session.

> [accordion] A temporary tracing run rejects the hook-trust option
>
> `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.

> [accordion] Codex uses an unexpected configuration directory
>
> 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.

> [accordion] Traces use unexpected settings
>
> 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`](https://docs.braintrust.dev/reference/cli/trace).

## Connect to Braintrust MCP

The Braintrust MCP server lets Codex query and update Braintrust data. MCP is configured independently from the tracing plugin.

> [accordion] Remove the retired Braintrust MCP plugin (if installed)
>
> 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:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> codex plugin list --json
> ```
>
> If `braintrust@braintrust-codex-plugins` appears in the installed plugins, remove it:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> codex plugin remove braintrust@braintrust-codex-plugins
> ```
>
> Keep the marketplace if you use the `trace-codex` tracing plugin.

**1. Choose authentication**

> [tab] OAuth (recommended)
>
> 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.

> [tab] API key
>
> Use an API key for clients without OAuth support or for programmatic connections. The server acts with the permissions of the account the key belongs to.
>
> 1. Create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
> 2. Configure your client to send this header on every request, replacing `YOUR_BRAINTRUST_API_KEY` with your key:
>
>    ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
>    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
>    ```

> [!NOTE]
>
> Your [`bt login`](https://docs.braintrust.dev/reference/cli/login) doesn't authenticate the MCP server.

**2. Choose your endpoint**

Use the endpoint for your organization's [data plane region](https://docs.braintrust.dev/admin/organizations.md#data-plane-region):

| Region | MCP endpoint |
| - | - |
| US | `https://api.braintrust.dev/mcp` |
| EU | `https://api-eu.braintrust.dev/mcp` |

Other connection details:

* **Self-hosted:** Copy the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli#cli-connect-codex-to-an-mcp-server) 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](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#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](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](https://docs.braintrust.dev/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](https://docs.braintrust.dev/evaluate/run-evaluations.md).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.