Skip to main content

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 session
  • AppServerClient: 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-level Codex facade
  • 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 Codex instance
  • 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

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)

Source distribution for codex-python 1.167.0
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)

Table of built distributions (wheels) for codex-python 1.167.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.167.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page