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

# Codex

> Trace Codex sessions to Braintrust and access your Braintrust data in Codex 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) passes your interactions with Codex to `bt`, which in turn uses a background process to build and deliver the trace to Braintrust.

Codex continues to communicate directly with its model provider, and tracing failures do not stop your Codex session.

### Set up tracing

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

<Steps>
  <Step title="Install Codex">
    If you haven't already, install the [Codex CLI](https://developers.openai.com/codex/cli). The tracing hooks require Bash, including on Windows.
  </Step>

  <Step title="Install and authenticate bt">
    Follow the [`bt` CLI quickstart](/docs/reference/cli/quickstart) to install `bt`, authenticate, and set your active context.
  </Step>

  <Step title="Enable tracing">
    <a id="settings" />

    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.

    The tracing file stores settings, not credentials. These settings apply across projects during normal sessions.

    For more information, see [`bt trace enable`](/docs/reference/cli/trace#bt-trace-enable).
  </Step>

  <Step title="Restart Codex and approve the plugin's hooks">
    Restart Codex, then run [`/hooks`](https://developers.openai.com/codex/hooks#review-and-trust-hooks) and trust the Braintrust hook definition. Codex does not run plugin hooks until you trust them.
  </Step>

  <Step title="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 [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page.
  </Step>
</Steps>

### What Braintrust traces

<a id="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 reconstructed from the session transcript, with conversation input, response output, and available 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`.

### Common workflows

<AccordionGroup>
  <Accordion title="Use different tracing settings for one session">
    Use [`bt trace run`](/docs/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`](/docs/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](/docs/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](/docs/reference/cli/trace#tag-traces).
  </Accordion>

  <Accordion title="Trace a saved Codex session">
    Codex stores session transcripts locally. Use [`bt trace import`](/docs/reference/cli/trace#bt-trace-import) to import a past session, even if tracing was not enabled when it ran.

    You can also attach an imported session to an existing span or experiment.
  </Accordion>

  <Accordion title="Resume a Codex session">
    When you resume a Codex session, new turns are added to its existing Braintrust trace.
  </Accordion>

  <Accordion title="Stop tracing Codex sessions">
    Use [`bt trace disable codex`](/docs/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.
  </Accordion>
</AccordionGroup>

### 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).
</Note>

<Steps>
  <Step title="Update bt">
    Follow the [CLI migration guide](/docs/reference/cli/migrate) to update `bt` to the latest version and complete the applicable migrations.
  </Step>

  <Step title="Update the tracing plugin">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace update codex
    ```

    [`bt trace update`](/docs/reference/cli/trace#bt-trace-update) updates the installed plugin without changing your saved tracing configuration.
  </Step>

  <Step title="Restart and verify Codex">
    Restart Codex and trust the updated Braintrust hook through `/hooks` if prompted. Run a short session and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.
  </Step>
</Steps>

### Migrate from an older plugin version

<a id="upgrade" />

To migrate to the latest version of the `trace-codex` plugin, follow these steps:

<Steps>
  <Step title="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).
    </Note>
  </Step>

  <Step title="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](/docs/reference/cli/migrate) (unless you've already done so).
    * Otherwise, [install `bt`](/docs/reference/cli/quickstart), authenticate, and set organization and project context.
  </Step>

  <Step title="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.
    </Note>

    <AccordionGroup>
      <Accordion title="trace-codex v1.0.1">
        <Note>
          Complete this section if you started your migration from a tracing-plugin version earlier than v1.0.1.
        </Note>

        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`](/docs/reference/cli/login).
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="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.
  </Step>

  <Step title="Restart and verify Codex">
    Restart Codex and trust the updated Braintrust hook through `/hooks` if prompted. Run a short session and confirm that its trace appears on the [**<Icon icon="activity" /> Logs**](https://www.braintrust.dev/app/~/logs) page in the intended Braintrust project.
  </Step>

  <Step title="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.
    </Note>

    <Accordion title="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`](/docs/reference/cli/trace#bt-trace-import) instead of the old parent-span settings.
    </Accordion>
  </Step>
</Steps>

### Troubleshooting tracing

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

<AccordionGroup>
  <Accordion title="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 and trust the Braintrust hook through `/hooks`.
  </Accordion>

  <Accordion title="Traces do not appear after setup">
    If Codex was running when its plugin or configuration changed, restart it. Confirm that Bash and `bt` are available to the process that launches Codex, and that you trusted the Braintrust hook through `/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](/docs/reference/cli/trace#project-log-permissions).

    For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](/docs/reference/cli/trace#troubleshooting) and the [CLI migration troubleshooting guide](/docs/reference/cli/migrate#troubleshooting).

    Tracing failures do not interrupt the Codex session.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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 `BT_DAEMON_CONFIG` override changes the tracing file path. If you use it, supply the same path when enabling tracing and launching Codex.
  </Accordion>

  <Accordion title="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`](/docs/reference/cli/trace).
  </Accordion>
</AccordionGroup>

## Connect to Braintrust MCP

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

### Set up the MCP server

<Steps>
  <Step title="Install Codex">
    If you haven't already, install the [Codex CLI](https://developers.openai.com/codex/cli).
  </Step>

  <Step title="Add the Braintrust MCP server">
    <Accordion title="Remove the retired Braintrust MCP plugin (if installed)">
      To connect Codex to the Braintrust MCP server, Braintrust previously published a `braintrust` plugin. However, the plugin has been retired in favor of Codex's native MCP configuration. If you installed the plugin, remove it before configuring the direct connection below.

      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.
    </Accordion>

    From the terminal, configure Codex's connection to the Braintrust MCP server:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    codex mcp add braintrust --url https://api.braintrust.dev/mcp
    ```

    See [Authentication](/docs/integrations/developer-tools/mcp#authentication) for API-key setup and [Endpoints](/docs/integrations/developer-tools/mcp#endpoints) for EU and self-hosted URLs.
  </Step>

  <Step title="Authenticate">
    Complete the browser sign-in if Codex starts an OAuth flow when you add the server. Otherwise, start it with:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    codex mcp login braintrust
    ```

    MCP authentication is separate from `bt login`, which authenticates the CLI and tracing integration.
  </Step>

  <Step title="Verify the connection">
    Open or restart Codex and run `/mcp` to confirm that the Braintrust server is connected. Ask Codex to list your recent Braintrust projects and confirm that it uses the Braintrust MCP server.
  </Step>
</Steps>

### Use MCP tools

Once connected, 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](/docs/integrations/developer-tools/mcp#what-the-mcp-can-do) for more workflows and example prompts.

### Troubleshooting MCP

<AccordionGroup>
  <Accordion title="Braintrust MCP tools do not appear">
    Run `/mcp` and confirm that the Braintrust remote server is registered and connected. Restart Codex after adding or changing the server.
  </Accordion>

  <Accordion title="MCP authentication or connection fails">
    Run `codex mcp login braintrust` to retry OAuth authentication. If you previously configured API-key authentication, remove `bearer_token_env_var` from the Braintrust server's entry in your Codex configuration before switching to OAuth.

    For authentication methods, regional and self-hosted endpoints, and network requirements, see the [Braintrust MCP guide](/docs/integrations/developer-tools/mcp#connect-your-client).
  </Accordion>
</AccordionGroup>

## Next steps

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