acodex

acodex is a typed Python SDK for the Codex CLI: run agent threads from Python (sync or async), stream JSONL events as parsed dataclasses, request structured JSON output, and attach images as inputs.

Key features

  • Typed surface: strict type hints + mypy strict, no runtime dependencies by default.

  • Quality gates: Ruff + mypy strict + 100% coverage.

  • Sync + async: Codex / Thread and AsyncCodex / AsyncThread.

  • Streaming events: Thread.run_streamed() yields parsed ThreadEvent dataclasses.

  • Structured output: output_type (Pydantic) or output_schema (JSON Schema, TS parity).

  • Images: pass UserInputLocalImage alongside text in a single turn.

  • Resume threads: resume_thread(thread_id) (threads persisted under ~/.codex/sessions).

  • Safety controls: expose Codex CLI controls as ThreadOptions (sandbox_mode, approval_policy, web_search_mode, working_directory, …).

  • TS SDK parity: the vendored TypeScript SDK is the source of truth; compatibility tests fail loudly on drift.

Quick links: docs.acodex.dev - GitHub - Issues - Codex CLI

Quickstart

Install (uv):

uv add acodex

from acodex import Codex

thread = Codex().start_thread(
    sandbox_mode="read-only",
    approval_policy="on-request",
    web_search_mode="disabled",
)
turn = thread.run("Say hello")
print(turn.final_response)

Next: Quickstart (structured output) and Streaming events (events).

Disclaimer

Important

acodex is an independently maintained SDK for the Codex CLI and is not affiliated with, sponsored by, or endorsed by OpenAI.

Documentation