codex-sdk

OpenAI Codex SDK

OpenAI Codex is a locally-run agentic coding assistant that enables building, fixing, and understanding code through AI assistance. The TypeScript SDK provides programmatic access to Codex's capabilities through a thread-based conversation model.

Quick Start

Install the SDK:

bun add @openai/codex-sdk

Basic usage:

import { Codex } from "@openai/codex-sdk";

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

// Execute single turn
const result = await thread.run("Diagnose and fix the CI failures");
console.log(result);

// Continue conversation
const nextTurn = await thread.run("Implement the fix");

Core Concepts

Thread-Based Architecture

Codex uses threads to manage conversations with the agent:

• startThread() - Begin new conversation
• run() - Execute single turn, get complete response
• runStreamed() - Stream responses with intermediate events
• resumeThread() - Resume saved conversation
• forkThread() - Branch conversation

Thread Persistence

Threads persist to ~/.codex/sessions for recovery:

// Save thread ID
const threadId = thread.id;

// Later, resume conversation
const resumedThread = codex.resumeThread(threadId);
const result = await resumedThread.run("Continue the task");

Model Selection

Configure model in thread options:

const thread = codex.startThread({
  model: "gpt-5.3-codex", // Latest, most capable — recommended default
  // Or: "gpt-5.3-codex-spark" — text-only, 1000+ tokens/s (ChatGPT Pro only, no vision)
  // Or: "gpt-5.1-codex-max" — long-horizon agentic tasks
  // Or: "gpt-5.2-codex" — previous generation
});

Key Features

Structured Output

Use JSON Schema for reliable structured responses:

const schema = {
  type: "object",
  properties: {
    findings: {
      type: "array",
      items: {
        type: "object",
        properties: {
          file: { type: "string" },
          line: { type: "number" },
          severity: { enum: ["error", "warning", "info"] },
          message: { type: "string" },
        },
      },
    },
    verdict: { enum: ["pass", "needs_changes"] },
  },
};

const result = await thread.run("Review this code", {
  outputSchema: schema,
});