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

# OpenAI Codex SDK

> Trace OpenAI Codex SDK runs in Braintrust to debug agent turns, tool calls, and code-editing workflows

If you are a coding agent, prefer the Braintrust [`bt` CLI](/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, such as ad-hoc lookups and exploration from your IDE.

The [OpenAI Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) (`@openai/codex-sdk`) is a TypeScript SDK for running Codex coding agents programmatically. Braintrust traces Codex threads, agent turns, and tool calls.

<Note>
  This page documents the `@openai/codex-sdk` SDK. To use the Codex CLI with Braintrust's MCP server instead, see [Codex](/integrations/developer-tools/codex).
</Note>

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-typescript">
    Setup
  </h2>

  Install Braintrust alongside the Codex SDK, then set your API keys. Requires `@openai/codex-sdk` v0.128.0 or later.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pnpm add braintrust @openai/codex-sdk
        ```

        ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        npm install braintrust @openai/codex-sdk
        ```
      </CodeGroup>
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=<your-braintrust-api-key>
      CODEX_API_KEY=<your-codex-api-key>
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-typescript">
    Auto-instrumentation
  </h2>

  To trace Codex runs without modifying your application code, initialize Braintrust normally, then run your app with Braintrust's import hook to patch the Codex SDK at runtime.

  <Steps>
    <Step title="Initialize Braintrust and run a thread">
      <CodeGroup>
        ```javascript title="trace-codex-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        import { initLogger } from "braintrust";
        import { Codex } from "@openai/codex-sdk";

        initLogger({
          projectName: "codex-example", // Replace with your project name
          apiKey: process.env.BRAINTRUST_API_KEY,
        });

        const codex = new Codex();
        const thread = codex.startThread();

        const result = await thread.run("Explain what this repository does in one sentence.");
        console.log(result.finalResponse);
        ```
      </CodeGroup>
    </Step>

    <Step title="Run with the import hook">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      node --import braintrust/hook.mjs trace-codex-auto.js
      ```

      The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

      <Note>
        If you're using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Step>
  </Steps>

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

  To trace the Codex SDK manually, wrap the imported module yourself with `wrapOpenAICodexSDK()`.

  <CodeGroup>
    ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import { initLogger, wrapOpenAICodexSDK } from "braintrust";
    import * as codexSDK from "@openai/codex-sdk";

    initLogger({
      projectName: "codex-example", // Replace with your project name
      apiKey: process.env.BRAINTRUST_API_KEY,
    });

    const { Codex } = wrapOpenAICodexSDK(codexSDK);

    const codex = new Codex();
    const thread = codex.startThread();

    const result = await thread.run("Explain what this repository does in one sentence.");
    console.log(result.finalResponse);
    ```
  </CodeGroup>

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  Braintrust patches the Codex SDK's `Thread.run` and `Thread.runStreamed` and captures:

  * Codex thread spans (`OpenAI Codex`), with the prompt as input and the agent's final response as output.
  * LLM turn spans (`OpenAI Codex LLM`), with reasoning and message output assembled from the stream events.
  * Tool call spans (`tool: command_execution`, `tool: web_search`, `tool: file_change`, and `tool: <name>` for MCP tools), with the tool input and result.
  * Thread metadata, including the model, sandbox mode, working directory, reasoning effort, web search mode, approval policy, and other `openai_codex.*` fields.
  * Token usage metrics (prompt, cached prompt, completion, reasoning, and total).
  * Errors captured on every span.

  <h2 id="resources-typescript">
    Resources
  </h2>

  * [OpenAI Codex SDK on npm](https://www.npmjs.com/package/@openai/codex-sdk)
  * [OpenAI Codex documentation](https://developers.openai.com/codex/)
</View>