codex-python
Python SDK for the Codex app-server.
This package exposes two supported APIs:
Codex: a simple, local convenience interface backed by a private stdio app-server sessionAppServerClient: a richer app-server client for thread management, streaming events, approvals, and typed protocol access
Canonical import paths:
- use
from codex import ...for the high-levelCodexfacade - use
from codex.app_server import ...for the raw app-server client and app-server option types
Install
pip install codex-python
Codex itself comes from OpenAI's openai-codex-cli-bin package, which is installed as a
dependency and pinned to the Codex version this SDK release targets, usually one with the same
minor version (SDK 1.X.* targets Codex 0.X.*).
It provides the codex CLI with its Code Mode host and sandbox helper on Linux, macOS, and
Windows, so no separate Codex install is needed.
Which API should I use?
Codex
Use Codex when you want the smallest surface area for local automation:
- one private local app-server session per
Codexinstance - stateless
run*()convenience (fresh internal thread per call) - stateful thread workflows when needed via
start_thread()/resume_thread() - simple request/response usage
- optional streaming over the exec event stream
- structured output via
TurnOptions(output_schema=...)
AppServerClient
Use AppServerClient when you want a deeper integration:
- persistent app-server connection
- thread objects and turn streams
- protocol-native notifications
- server-driven requests such as tool callbacks and approvals
- typed protocol models and raw JSON-RPC access when needed
Quickstart: Codex
from codex import Codex, ThreadStartOptions
client = Codex()
# Simplest one-shot call.
summary = client.run_text("Diagnose the failing tests and propose a fix")
print(summary)
# One-shot call with thread-scoped defaults for that run's fresh internal thread.
summary = client.run_text(
"Diagnose the failing tests in this repo",
thread_options=ThreadStartOptions(
cwd="/repo",
model="gpt-5",
),
)
print(summary)
Use thread_options= on run(), run_text(), run_json(), and run_model() when you want to
set defaults on the fresh internal thread created for that one-shot call. Use
start_thread() / resume_thread() when later runs should share context.
More Codex examples: docs/exec_api.md
Quickstart: AppServerClient
from codex.app_server import AppServerClient, AppServerClientInfo, AppServerInitializeOptions
initialize_options = AppServerInitializeOptions(
client_info=AppServerClientInfo(
name="my_integration",
title="My Integration",
version="0.1.0",
)
)
with AppServerClient.connect_stdio(initialize_options=initialize_options) as client:
thread = client.start_thread()
summary = thread.run_text("Briefly summarize this repository's purpose.")
print(summary)
More app-server examples: docs/app_server.md
For websocket transport, install the optional extra: pip install "codex-python[websocket]".
Dynamic tools
Decorator-driven dynamic tools are available on both SDK surfaces.
Codex
from codex import Codex, dynamic_tool
@dynamic_tool
def lookup_ticket(id: str) -> str:
"""Look up a support ticket by id."""
return f"Ticket {id}: Login requests time out in eu-west-1."
client = Codex()
summary = client.run_text(
"Use the lookup_ticket dynamic tool for ticket 123 and summarize the result.",
tools=[lookup_ticket],
)
print(summary)
AppServerClient
For a complete app-server example using the same decorator-driven flow, see examples/app_server_dynamic_tool.py.
Structured output
Codex
from codex import Codex, TurnOptions
schema = {
"type": "object",
"properties": {"summary": {"type": "string"}},
"required": ["summary"],
"additionalProperties": False,
}
client = Codex()
payload = client.run_json("Summarize repository status", TurnOptions(output_schema=schema))
print(payload["summary"])
AppServerClient
from pydantic import BaseModel
from codex.app_server import AppServerClient, AppServerTurnOptions
class Summary(BaseModel):
summary: str
with AppServerClient.connect_stdio() as client:
thread = client.start_thread()
result = thread.run_model(
"Summarize repository status",
Summary,
)
print(result.summary)
run_model() uses Summary both as the validation model and, by default, as the output schema sent
to Codex. If you want JSON back without validation, you can also pass the model class directly to
output_schema, for example thread.run_json(..., AppServerTurnOptions(output_schema=Summary)).
Streaming
Codex stream
from codex import Codex
from codex.protocol import types as protocol
client = Codex()
stream = client.run("Investigate this bug")
for event in stream:
if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
print(event.params.delta, end="", flush=True)
print()
Codex.run*() starts a fresh internal thread for each call. Use
start_thread() or resume_thread() when you want later runs to share context.
High-level Codex helpers raise ThreadRunError on failed or interrupted terminal turns and
preserve the final turn metadata on the exception for debugging and UI handling.
App-server stream
from codex.app_server import AppServerClient
from codex.protocol import types as protocol
with AppServerClient.connect_stdio() as client:
thread = client.start_thread()
stream = thread.run("Investigate this bug")
for event in stream:
if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
print(event.params.delta, end="", flush=True)
print()
Advanced app-server usage, including typed stable RPC domains such as client.models and the raw client.rpc fallback: docs/app_server_advanced.md
Examples
- examples/basic_conversation.py: minimal
Codexflow - examples/basic_dynamic_tool.py: high-level
Codexdynamic tool flow - examples/app_server_conversation.py: minimal app-server flow
- examples/app_server_websocket_conversation.py: minimal websocket app-server flow
- examples/app_server_stream_events.py: protocol-native app-server streaming
- examples/app_server_tool_handler.py: typed app-server request handling
- examples/app_server_dynamic_tool.py: decorator-driven dynamic tool registration
Codex runtime
By default, the SDK runs codex app-server from the installed openai-codex-cli-bin package and
puts that package's helper tools on the server's PATH. If the package is missing, it falls back
to codex on PATH. Use the Codex version targeted by your SDK release for protocol
compatibility.
Releases up to 1.159.2 bundled only codex-app-server, without its Code Mode host. Since
Codex 0.147, models that require Code Mode cannot run tools without that host, so upgrade or set
codex_path_override to a full Codex install.
You can override the executable path with:
CodexOptions(codex_path_override=...)codex.app_server.AppServerProcessOptions(codex_path_override=...)
Overrides named codex-app-server* run directly; other overrides run with the app-server
subcommand.
Development
make lint
make test
make test emits a terminal coverage report, writes coverage.xml, and enforces the repository
coverage gate.
Metadata
Release files for codex-python 1.167.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codex_python-1.167.0.tar.gz | 128.3 kB | With provenance | Details for codex_python-1.167.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codex_python-1.167.0-py3-none-any.whl | Python 3 | none | any | Details for codex_python-1.167.0-py3-none-any.whl |
Total release size: 269.6 kB
Release files / codex_python-1.167.0.tar.gz
| Download URL | codex_python-1.167.0.tar.gz |
|---|---|
| Size | 128.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b7b0d23a4aacbd0ebabfa749e808841370a8a4cbba122a8c78c1fc0f39c2bd2d
|
|
BLAKE2b-256 checksum How to use checksums |
976dafce1d0ba378888a42ab23e8c055f6f8f460a5cfb251ea8d5a7538e2d755
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / codex_python-1.167.0-py3-none-any.whl
| Download URL | codex_python-1.167.0-py3-none-any.whl |
|---|---|
| Size | 141.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
095330f0140a38c01a768d868c4c629d56237a984b07cdef1a05402e8a1efedf
|
|
BLAKE2b-256 checksum How to use checksums |
90396294b4f4314d650d4b70110db45cd2c5fec12e33c0606af75603821fb021
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logSecurity for codex-python 1.167.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for codex_python-1.167.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.