SDK – Codex

If you use Codex through the Codex CLI, the IDE extension, or Codex Web, you can also control it programmatically.

Use the SDK when you need to:

• Control Codex as part of your CI/CD pipeline
• Create your own agent that can engage with Codex to perform complex engineering tasks
• Build Codex into your own internal tools and workflows
• Integrate Codex within your own application

TypeScript library

The TypeScript library provides a way to control Codex from within your application that’s more comprehensive and flexible than non-interactive mode.

Use the library server-side; it requires Node.js 18 or later.

Installation

To get started, install the Codex SDK using npm:

npm install @openai/codex-sdk

Usage

Start a thread with Codex and run it with your prompt.

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

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result);

Call run() again to continue on the same thread, or resume a past thread by providing a thread ID.

// running the same thread
const result = await thread.run("Implement the plan");

console.log(result);

// resuming past thread

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2);

For more details, check out the TypeScript repo.

Python library

The Python SDK is experimental and controls the local Codex app-server over JSON-RPC. It requires Python 3.10 or later and a local checkout of the open-source Codex repo.

Installation

From the Codex repo root, install the SDK in editable mode:

cd sdk/python
python -m pip install -e .

For manual local SDK usage, pass AppServerConfig(codex_bin=...) to point at a local codex binary, or use the repo examples and notebook bootstrap.

Usage

Start Codex, create a thread, and run a prompt:

from codex_app_server import Codex

with Codex() as codex:
    thread = codex.thread_start(model="gpt-5.4")
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Use AsyncCodex when your application is already asynchronous:

import asyncio

from codex_app_server import AsyncCodex

async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4")
        result = await thread.run("Implement the plan")
        print(result.final_response)

asyncio.run(main())

For more details, check out the Python repo.