> ## 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 CLI sessions to Braintrust and access your Braintrust data in Codex through the MCP server

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[Codex](https://openai.com/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](https://github.com/braintrustdata/braintrust-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](/docs/reference/cli/trace) to build and send traces to Braintrust.
* Authentication happens through [`bt login`](/docs/reference/cli/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](#what-gets-traced) for details.

### Set up tracing

<Note>
  Upgrading from `trace-codex` before v1.0.1? See [Upgrade](#upgrade).
</Note>

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

  <Step title="Install bt and authenticate">
    Tracing runs through `bt`, so [install the CLI](/docs/reference/cli/quickstart#install) and [authenticate](/docs/reference/cli/quickstart#authenticate-and-set-context):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    curl -fsSL https://bt.dev/cli/install.sh | bash
    bt login
    ```

    You can also install with [mise](/docs/reference/cli/quickstart#install-with-mise) or [npm](/docs/reference/cli/quickstart#install-with-npm), or with [PowerShell on Windows](/docs/reference/cli/quickstart#install).
  </Step>

  <Step title="Configure the plugin">
    After `bt` is installed and authenticated, run the following command:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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.

    <Note>
      To learn what this command writes and how to change it later, see [Settings](#settings).
    </Note>
  </Step>

  <Step title="Approve the plugin's hooks">
    To load the plugin, restart Codex.

    Then run [`/hooks`](https://developers.openai.com/codex/hooks#review-and-trust-hooks) in Codex and trust the Braintrust hook definition. Codex does not run plugin hooks until you trust them.
  </Step>

  <Step title="Log a test trace">
    Start a short Codex session and ask it to do something simple:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    codex "Say hello from a traced Codex session"
    ```

    When the session finishes, open your Braintrust project and check that the trace appears in Logs.
  </Step>
</Steps>

### 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`](/docs/reference/cli/trace#bt-trace-setup) 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`](/docs/reference/cli/quickstart#authenticate-and-set-context)). |
| 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`](/docs/reference/cli/quickstart#authenticate-and-set-context) or `BRAINTRUST_API_KEY`. See [credential precedence](/docs/reference/cli/overview#credential-precedence).
* To use different settings for one launched session without changing saved configuration, use [`bt trace run`](/docs/reference/cli/trace#bt-trace-run).
* To switch projects, re-run setup:

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

### Common workflows

<Accordion title="Use custom settings for one run">
  To apply custom settings to a single Codex run, launch Codex with [`bt trace run`](/docs/reference/cli/trace#bt-trace-run):

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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 `--`:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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`](https://developers.openai.com/codex/cli/reference#global-flags) to the Codex arguments only when you control and trust every enabled hook.
</Accordion>

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

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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`](/docs/reference/cli/trace#bt-trace-import) for details, including following a live session with `--attach`.
</Accordion>

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

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

<Steps>
  <Step title="Update bt">
    Update `bt` before updating `trace-codex`.

    <Note>
      If you're also migrating from an older `bt` version with `bt auth` commands, review the [CLI migration guide](/docs/reference/cli/migrate). It explains how saved logins carry over, how profiles and organizations changed, and which commands replaced the old auth commands.
    </Note>

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

    `bt update` updates installs made with the standalone shell or PowerShell installer. If you installed with [mise](/docs/reference/cli/quickstart#install-with-mise) or [npm](/docs/reference/cli/quickstart#install-with-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](/docs/reference/cli/quickstart#install).
  </Step>

  <Step title="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`](/docs/reference/cli/quickstart#authenticate-and-set-context). You can also authenticate with `BRAINTRUST_API_KEY`.
  </Step>

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

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    bt trace setup codex --project my-project   # Replace with your project name
    ```

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

  <Step title="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`](/docs/reference/cli/quickstart#authenticate-and-set-context), 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>`](/docs/reference/cli/trace#bt-trace-import) 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.                                                                                                                                                                                                                                                                       |
  </Step>
</Steps>

For current settings and how to change them, see [Settings](#settings).

### Troubleshooting

<Accordion title="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`](https://developers.openai.com/codex/cli/reference#global-flags) (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`](/docs/reference/cli/quickstart#authenticate-and-set-context) 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.
</Accordion>

## 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

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

  <Step title="Set your API key">
    Set the `BRAINTRUST_API_KEY` environment variable with your API key:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    export BRAINTRUST_API_KEY="your-api-key-here"
    ```
  </Step>

  <Step title="Add the Braintrust MCP server">
    Edit `~/.codex/config.toml` and add the Braintrust MCP server configuration:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    [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.
  </Step>

  <Step title="Verify the setup">
    Launch Codex with the environment variable set:

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

    Run the `/mcp` command to verify Braintrust is installed and accessible.
  </Step>
</Steps>

### 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](/docs/integrations/developer-tools/mcp#what-the-mcp-can-do) 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

<Accordion title="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`](https://developers.openai.com/codex/mcp) in Codex to see available MCP servers.
  * Try restarting Codex.
</Accordion>

<Accordion title="MCP authentication fails">
  * Verify your API key is correct (no extra spaces).
  * Ensure you can log into [Braintrust](https://www.braintrust.dev) using the account associated with the API key.
  * Generate a new API key if needed.
</Accordion>

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

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](/docs/reference/cli/trace), including session imports and per-run tracing.
* **Run evaluations**: Check out the [evaluation guide](/docs/evaluate/run-evaluations) to learn evaluation patterns.
* **Explore MCP tools**: See the [MCP documentation](/docs/integrations/developer-tools/mcp#tools) for all available commands.
* **Query with SQL**: Learn how to [query with SQL](/docs/reference/sql) for complex data analysis.
* **Browse the plugin**: See the [Codex plugin repository](https://github.com/braintrustdata/braintrust-codex-plugin) for releases and distribution files. The shared [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins) contains the source for all Braintrust coding-agent plugins.