codex-app-server-sdk¶
Async Python client library for codex app-server over stdio and websocket.
Upgrading to 0.4.0 requires a compatibility review
This release changes behavior for existing applications. Stream-based
approval responders must set approval_mode="manual"; failed/interrupted
turns now raise, and cancellation, initialization, unanswered user questions,
and custom transport expectations also change.
Read the 0.3.2 → 0.4.0 migration guide.
Why use this client?¶
Use Codex directly from your application's asyncio event loop, choose or
replace the transport, and control the Codex runtime independently. The
conversation API adds completed-step streaming, resumable inactivity timeouts,
and cancellation with unread-event recovery.
Both this library and the official openai-codex Python SDK use the Codex
app-server protocol, with different integration choices:
| Area | codex-app-server-sdk |
openai-codex |
|---|---|---|
| Execution | Native asyncio client; asynchronous protocol I/O on your event loop |
Synchronous client with an async wrapper that offloads blocking operations to background threads |
| Transport | Public, replaceable Transport; built-in stdio and WebSocket support |
SDK-managed subprocess communicating through line-delimited JSON over stdio |
| Protocol access | Flexible dictionary-based RPC via request(...), plus high-level conversation models |
Extensive generated types, typed responses, and typed notifications |
| Runtime management | You supply and manage Codex; choose an executable or connect to an existing WebSocket server | Installs an exactly pinned Codex runtime dependency by default |
This client's native async I/O and transport flexibility suit applications with their own runtime or connection management. The official SDK offers broader generated type coverage and a reproducible runtime default. You are responsible for installing and updating Codex when using this client.
Comparison verified against the published
openai-codex 0.156.1
source and package metadata on 2026-09-23. The official SDK also supports a
CodexConfig(codex_bin=...) override
for selecting a different local executable.
Documentation¶
This documentation is organized around:
- task-oriented guides (
getting started,conversation,threads/config) - operational behavior (
timeouts,continuation,cancel, guarantees) - complete API reference generated from source docstrings
Quick links¶
- Start here: Getting started
- Upgrade an existing app: Migrating to 0.4.0
- Streaming semantics: Conversation APIs
- Plan mode and user confirmation: Human-in-the-loop
- Long-running turn control: Timeouts, continuation, cancel
- Thread/model/config scope: Threads and configuration
- Ready-to-run scripts: Examples
- Method-level mapping: Protocol mapping
- Generated reference: API reference
Install¶
Install uv (if needed):
curl -LsSf https://astral.sh/uv/install.sh | sh
Install the package from PyPI:
uv add codex-app-server-sdk
Or pip-compatible install in the active environment:
uv pip install codex-app-server-sdk
Contributor docs workflow¶
For versioning, package validation, and publishing, see the release procedure.
Install development dependencies:
uv sync --group dev
Serve docs locally:
uv run zensical serve
Build docs:
uv run zensical build