Codex SDK for Python

Embed the Codex agent in Python workflows by spawning the Codex CLI and consuming structured events.

The SDK launches the bundled codex binary (or a custom path) and exchanges JSONL events over stdin/stdout.

Installation

Until packages are published, install locally in editable mode:

pip install -e .

Requires Python 3.9+ and a Codex binary reachable either via the packaged vendor path or codex_path_override.

Quickstart

from codex_sdk import Codex

codex = Codex()
thread = codex.start_thread()
turn = thread.run("Diagnose the test failure and propose a fix")

print(turn.final_response)
print(turn.items)

Call run() again on the same Thread to continue the conversation.

next_turn = thread.run("Implement the fix")

Streaming responses

run() buffers events. To react to intermediate progress—tool calls, streamed responses, and file change notifications—use run_streamed() instead. It returns a generator of structured events.

from codex_sdk import ThreadEvent

stream = thread.run_streamed("Diagnose the test failure and propose a fix")

for event in stream.events:
    if event.type == "item.completed":
        print("item", event.item)
    elif event.type == "turn.completed":
        print("usage", event.usage)

Structured output

Provide a JSON schema per turn to receive structured assistant responses.

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

from codex_sdk import TurnOptions

turn = thread.run("Summarize repository status", TurnOptions(output_schema=schema))
print(turn.final_response)

Attaching images

Pass structured input entries when including images alongside text. Text entries are concatenated into the prompt; image entries are forwarded to the Codex CLI via --image.

turn = 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 persist in ~/.codex/sessions. If you lose the in-memory Thread, reconstruct it with resume_thread() and keep going.

import os

saved_thread_id = os.environ["CODEX_THREAD_ID"]
thread = codex.resume_thread(saved_thread_id)
thread.run("Implement the fix")

Working directory controls

Codex runs in the current working directory by default. To bypass the Git repository check for temporary directories, pass skip_git_repo_check=True when creating a thread.

from codex_sdk import ThreadOptions

thread = codex.start_thread(ThreadOptions(working_directory="/path/to/project", skip_git_repo_check=True))

Controlling the Codex CLI environment

By default, the CLI inherits os.environ. Override it when you need a sandboxed environment and the SDK will inject required variables (OPENAI_BASE_URL, CODEX_API_KEY, and the SDK originator marker).

from codex_sdk import CodexOptions

codex = Codex(CodexOptions(env={"PATH": "/usr/local/bin"}))

Options reference

CodexOptions: codex_path_override, base_url, api_key, env
ThreadOptions: model, sandbox_mode, working_directory, skip_git_repo_check, model_reasoning_effort, network_access_enabled, web_search_enabled, approval_policy, additional_directories
TurnOptions: output_schema, cancellation_event

Running tests

python -m unittest discover -v

Set codex_path_override if the bundled binary is unavailable; the test suite expects a Codex binary and will exercise a local HTTP proxy to avoid external calls.

3.8 KiB Raw Blame History