@openai/codex-sdk

Codex SDK

Embed the Codex agent in your workflows and apps.

The TypeScript SDK wraps the codex CLI from @openai/codex. It spawns the CLI and exchanges JSONL events over stdin/stdout.

Installation

npm install @openai/codex-sdk

Requires Node.js 18+.

Quickstart

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

const codex = new Codex();
const thread = codex.startThread();
const turn = await thread.run("Diagnose the test failure and propose a fix");

console.log(turn.finalResponse);
console.log(turn.items);

Call run() repeatedly on the same Thread instance to continue that conversation.

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

Streaming responses

run() buffers events until the turn finishes. To react to intermediate progress—tool calls, streaming responses, and file change notifications—use runStreamed() instead, which returns an async generator of structured events.

const { events } = await thread.runStreamed("Diagnose the test failure and propose a fix");

for await (const event of events) {
  switch (event.type) {
    case "item.completed":
      console.log("item", event.item);
      break;
    case "turn.completed":
      console.log("usage", event.usage);
      break;
  }
}

Structured output

The Codex agent can produce a JSON response that conforms to a specified schema. The schema can be provided for each turn as a plain JSON object.

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 });
console.log(turn.finalResponse);

You can also create a JSON schema from a Zod schema using the zod-to-json-schema package and setting the target to "openAi".

const schema = z.object({
  summary: z.string(),
  status: z.enum(["ok", "action_required"]),
});

const turn = await thread.run("Summarize repository status", {
  outputSchema: zodToJsonSchema(schema, { target: "openAi" }),
});
console.log(turn.finalResponse);

Attaching images

Provide structured input entries when you need to include images alongside text. Text entries are concatenated into the final prompt while image entries are passed to the Codex CLI via --image.

const turn = await thread.run([
  { type: "text", text: "Describe these screenshots" },
  { type: "local_image", path: "./ui.png" },
  { type: "local_image", path: "./diagram.jpg" },
]);

Resuming an existing thread

Threads are persisted in ~/.codex/sessions. If you lose the in-memory Thread object, reconstruct it with resumeThread() and keep going.

const savedThreadId = process.env.CODEX_THREAD_ID!;
const thread = codex.resumeThread(savedThreadId);
await thread.run("Implement the fix");

Working directory controls

Codex runs in the current working directory by default. To avoid unrecoverable errors, Codex requires the working directory to be a Git repository. You can skip the Git repository check by passing the skipGitRepoCheck option when creating a thread.

const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

Controlling the Codex CLI environment

By default, the Codex CLI inherits the Node.js process environment. Provide the optional env parameter when instantiating the Codex client to fully control which variables the CLI receives—useful for sandboxed hosts like Electron apps.

const codex = new Codex({
  env: {
    PATH: "/usr/local/bin",
  },
});

The SDK still injects its required variables (such as CODEX_API_KEY) on top of the environment you provide. If you set baseUrl, the SDK passes it as a --config openai_base_url=... override.

Passing --config overrides

Use the config option to provide additional Codex CLI configuration overrides. The SDK accepts a JSON object, flattens it into dotted paths, and serializes values as TOML literals before passing them as repeated --config key=value flags.

const codex = new Codex({
  config: {
    show_raw_agent_reasoning: true,
    sandbox_workspace_write: { network_access: true },
  },
});

For configuration keys that cannot be expressed as dotted paths, pass raw TOML overrides with configOverrides. Each entry is forwarded unchanged as a separate --config argument, without modifying CODEX_HOME:

const codex = new Codex({
  config: { default_permissions: "audit" },
  configOverrides: ['permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}'],
});

Raw overrides are applied after structured config overrides and take precedence over them. SDK-managed settings, such as baseUrl, and thread-specific options are applied afterward and take precedence.

Similar packages

Other packages similar to @openai/codex-sdk

@anthropic-ai/claude-agent-sdk

An SDK for building applications around Claude Code's agent capabilities, including working with codebases and handling tool-driven tasks. It is a close alternative for coding-agent workflows, but uses Anthropic's Claude models and APIs rather than Codex.

@github/copilot-sdk

An SDK for integrating GitHub Copilot's coding-agent capabilities into applications. It overlaps in programmatic coding-agent workflows, while being tied to GitHub Copilot's ecosystem and offering a different runtime and API.

@google/gemini-cli

A package for Google's Gemini CLI coding agent. It can work with code and developer tools, but is primarily a command-line application rather than an SDK centered on embedding Codex threads in a Node.js app.

@openai/agents

OpenAI's general-purpose agent SDK for building tool-using agents and orchestrating workflows. It can be used for coding-related agents, but is broader in scope; the Codex SDK is specifically oriented around delegating coding tasks to Codex.