Setup Install Braintrust alongside the Codex SDK, then set your API keys. Requires `@openai/codex-sdk` v0.128.0 or later. ```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 ``` ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} BRAINTRUST_API_KEY= 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. ```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); ``` ```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. If you’re using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#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: ` 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/)