OpenAI Codex SDK

Setup

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

Install packages

pnpm add braintrust @openai/codex-sdk

npm install braintrust @openai/codex-sdk

Set environment variables

.env

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.

Initialize Braintrust and run a thread

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

Run with the import hook

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.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

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

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.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources