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

# OpenAI Codex SDK

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

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 trace interactive Codex CLI sessions or use the Codex CLI with Braintrust's MCP server instead, see [Codex](https://docs.braintrust.dev/integrations/developer-tools/codex.md).

**TypeScript**

## Setup

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

**1. Install packages**

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

**2. 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>
```

## Auto-instrumentation

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.

**1. Initialize Braintrust and run a thread**

```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);
```

**2. 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 and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader.

> [!NOTE]
>
> If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) for plugin and loader setup.

## Manual instrumentation

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

```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);
```

## What Braintrust traces

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.

## Resources

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


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