> ## 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](/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.

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](/docs/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](/docs/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>