Embedding Codex with the SDK

Before any API surface, fix one idea: the Codex SDK does not contain a second agent — it drives the one you already have. When you install @openai/codex-sdk or openai-codex, you are installing a programmatic client that talks to your local Codex CLI. The CLI (a Rust binary) is still the thing that reasons, edits files, runs commands, and enforces the sandbox. The SDK just starts it, hands it your prompt, and reads back structured events.

That single fact explains almost everything about how the SDK behaves:

• It reuses your existing auth (ChatGPT-account sign-in or API key) and your ~/.codex/config.toml — there is no separate login.
• It honors your AGENTS.md files, the same way an interactive session does.
• Its threads are persisted under ~/.codex/sessions — the very same JSONL session store the CLI writes — which is why you can resume them later (and even resume a CLI session's id from the SDK, or vice versa).
• Because the agent is the CLI, the SDK's capabilities track the CLI's. New CLI features show up to the SDK automatically; this is also why their versions are coupled (see the last section).

Reach for the SDK when codex exec and the GitHub Action stop being enough: when you want to react to intermediate tool calls in code, fan out many threads, wire Codex into a long-running service or chat bot, or build a custom approval/UI layer around the agent.

The TypeScript package is @openai/codex-sdk (npm install @openai/codex-sdk), and it requires Node.js 18+. The whole surface is three nouns: a Codex client, a thread (one conversation), and a turn (one run within that conversation).

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

const codex = new Codex();                  // reuses your CLI auth + config
const thread = codex.startThread();         // a new conversation
const turn = await thread.run("Diagnose the failing test and propose a fix");
console.log(turn.finalResponse);            // the agent's final message

The pieces, with the options that matter:

Inputs can be a plain string or an array of entries ({type:"text", text} or {type:"local_image", path}), so you can attach screenshots. The result — a Turn — exposes finalResponse (the final assistant message as a string) and items (the steps the agent took). Token usage arrives on the turn.completed event when you stream.

Because the CLI normally requires a Git repo, set skipGitRepoCheck: true when you run against a non-repo directory.

thread.run() resolves only when the whole turn is finished — fine for batch jobs, but useless if you want to show progress, react to a tool call, or surface file changes live. For that, use thread.runStreamed(input), which returns an object with an async event generator you iterate:

const { events } = await thread.runStreamed("Refactor the auth module and run the tests");

for await (const event of events) {
  if (event.type === "item.completed") {
    console.log("step:", event.item);        // a completed agent step
  }
  if (event.type === "turn.completed") {
    console.log("usage:", event.usage);      // token counts for the turn
  }
}

The stream emits the same family of events the CLI's --json mode emits — this is the contract you parse in automation:

Think of run() as the convenience wrapper and runStreamed() as the real-time view of the same turn. Use streaming when you're building a UI, a chat bot, or anything that should not freeze until the agent is completely done.

If code is going to consume the agent's answer, you do not want a paragraph of prose — you want JSON that matches a contract. The SDK exposes this through the outputSchema option on run(), the programmatic twin of codex exec --output-schema. You pass a JSON Schema; the final response conforms to it.

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    status: { type: "string", enum: ["ok", "action_required"] },
  },
  required: ["summary", "status"],
  additionalProperties: false,
} as const;

const turn = await thread.run("Summarize repository status", { outputSchema: schema });
const result = JSON.parse(turn.finalResponse);   // matches the schema above
if (result.status === "action_required") { /* branch on it safely */ }

This is the headless equivalent of "structured outputs": instead of writing brittle regexes against free text, you get a typed object you can branch on. It's the single most important habit for anything machine-consumed — a CI gate, a Slack notifier, a dashboard — because it turns the agent's output into a stable interface rather than a string you hope stays formatted.

A long-running automation rarely lives in one process. You start a thread in one job, the process exits, and a later job needs to continue the same conversation — with all its accumulated context. Because threads persist under ~/.codex/sessions, you only need to carry one thing across the boundary: thread.id.

// First run — persist the id somewhere durable
const codex = new Codex();
const thread = codex.startThread();
await thread.run("Investigate the CI failure and write a plan");
await saveThreadId(thread.id);              // e.g. to a DB or job output

// Later run — rebuild the thread from its id and continue
const resumed = codex.resumeThread(await loadThreadId());
await resumed.run("Now implement the plan you wrote");

codex.resumeThread(threadId) reconstructs a Thread you lost from memory — its conversation history comes from the session store on disk, not your process. This is exactly how a two-stage "plan, then approve, then apply" workflow is built: stage one writes a plan and saves the id; a human approves; stage two resumes and acts. The session id is the durable handle; everything else is reconstructed.

The Python package is openai-codex (pip install openai-codex) and requires Python 3.10+. Instead of spawning the CLI over stdio, it controls the local Codex app-server over JSON-RPC (and ships a pinned CLI runtime). The object model maps almost one-to-one onto the TypeScript API:

from openai_codex import Codex, Sandbox      # package name: openai-codex

with Codex() as codex:
    thread = codex.thread_start(
        model="<model>",                     # look up current ids at developers.openai.com/codex/models
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)             # note the snake_case field

The naming differences are the things to memorize:

Use the with context manager (or AsyncCodex in async code) so the app-server connection is opened and torn down cleanly. Everything you learned about threads, runs, and resuming carries over — only the casing and the transport change.

The SDK gives you the same OS-enforced sandbox the CLI does — the boundary that decides WHERE the agent can read, write, and reach the network. (It's independent from approvals, which decide WHEN Codex must ask; that distinction from the CLI lessons holds here too.) There are three presets:

Two practical rules:

• Start narrow. Default to read-only and grant workspace_write only to the threads that genuinely need to edit. Reserve full access for throwaway runners.
• You can change the sandbox mid-thread. In Python you pass sandbox= to run() to widen (or narrow) permissions on a later turn — e.g. read-only while the agent investigates and writes a plan, then workspace_write once you've approved it. The same WHERE/WHEN model from the interactive CLI applies; the SDK simply lets your code make the call.

Here is the one operational gotcha that bites people. Because each SDK drives the CLI (the TS SDK spawns it; the Python SDK pins a CLI runtime), the SDK and CLI versions are coupled and rev together. A new CLI feature lands, the SDK bumps to expose it, and a mismatched pair can misbehave. So do not hard-code or memorize version numbers — they rot on a weekly cadence. Look them up live:

The same volatility applies to model names. The recommended default is a moving target on the gpt-5.x line — so leave model unset to track it (especially with ChatGPT-account auth), or pin a specific id only after confirming it on the models page. Build your automation to read versions and model availability from these sources, not from a constant in your code.

# Pin both together so they can't drift apart in CI:
npm install @openai/codex-sdk@latest    # then commit the lockfile
codex --version                          # confirm the CLI the SDK will drive