codex-python

Python SDK for Codex with bundled codex binaries inside platform wheels.

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

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

Bundled binary behavior

By default, the SDK resolves the bundled binary at:

codex/vendor/<target-triple>/codex-app-server/{codex-app-server|codex-app-server.exe}

The bundled app-server runs directly. If it is not present, for example in a source checkout, the SDK falls back to codex app-server using codex on PATH.

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.

If you want to test vendored-binary behavior locally, fetch binaries into codex/vendor:

python scripts/fetch_codex_binary.py --target-triple x86_64-unknown-linux-musl

Project links

Data verified by PyPI on Jul 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.146.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for gersmann from gravatar.com gersmann

GitHub Statistics

Data verified by PyPI on Jul 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.12

Provides Extra

websocket

Tags

codex sdk cli automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codex_python-1.145.0.tar.gz (104.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

codex_python-1.145.0-cp312-abi3-win_arm64.whl (98.6 MB view details)

Uploaded CPython 3.12+Windows ARM64

codex_python-1.145.0-cp312-abi3-win_amd64.whl (85.7 MB view details)

Uploaded CPython 3.12+Windows x86-64

codex_python-1.145.0-cp312-abi3-musllinux_1_2_x86_64.whl (100.6 MB view details)

Uploaded CPython 3.12+musllinux: musl 1.2+ x86-64

codex_python-1.145.0-cp312-abi3-musllinux_1_2_aarch64.whl (94.6 MB view details)

Uploaded CPython 3.12+musllinux: musl 1.2+ ARM64

codex_python-1.145.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (100.4 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ x86-64

codex_python-1.145.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (94.5 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

codex_python-1.145.0-cp312-abi3-macosx_11_0_arm64.whl (91.0 MB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

codex_python-1.145.0-cp312-abi3-macosx_10_12_x86_64.whl (97.7 MB view details)

Uploaded CPython 3.12+macOS 10.12+ x86-64

File details

Details for the file codex_python-1.145.0.tar.gz.

File metadata

  • Download URL: codex_python-1.145.0.tar.gz
  • Upload date:
  • Size: 104.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for codex_python-1.145.0.tar.gz
Algorithm Hash digest
SHA256 7808de7ecf1c51602c196d866a2b56e77ab29afbd37b8d21eed798b5a6fcbcc2
MD5 392819f686dc3f597f4b88484b3f1fbf
BLAKE2b-256 c49b223d086042b0927d25234f2b49567183d600223457e71c4922dc4b1afcec

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0.tar.gz:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 8fd80c44640e1b1963fb3753c9cb3da5ae90612c7423fcb3f356b9db3ead6047
MD5 170c73187af6fd70c4d2df252233db4c
BLAKE2b-256 4c2e45a966f15acf011c29d97be3aabeff1e73dd1214e22aab5c6101a1343b7a

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-win_arm64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e261e04b1bc602ea9d17fbc2cfd0d10fd47490727ab934ec40618ef61f516d58
MD5 f8a6d4daf635031a78eeb9fdc0dece94
BLAKE2b-256 7f6a8bb76d3548c9e999df92a835a4889e35aecaf196adf0cf6d27c0370c016e

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-win_amd64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 9af44a2ecaa8936753b5c41d72bb0c0e4d60ff6105b62a0dbe40e2f819d414f3
MD5 ffe72e1ccb6129178f8c0b9661425f1b
BLAKE2b-256 016ac85ac43f835c18f5fb7d4f8040ecb425a8a647631cb5cbc1f4bfecb196c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-musllinux_1_2_x86_64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 77759e8a92a054667dae6307114bfcff50d65d809e305dcd3c44c556fab77204
MD5 5a97b9167976d1430db4ee793a084923
BLAKE2b-256 1f200437d8be5957b40b8381446d9a62786d0129b26baf570272ca54a66ebb88

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-musllinux_1_2_aarch64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b8d1376d9242ef0f5e8cd5e79f8e88810617bca9e84fb8ffb5991b7d26220f4f
MD5 8fac9f84a4aaeca1291ac7ac6d9e4537
BLAKE2b-256 54ff1ab9e6937502d0c060e3be6dec9a10a35eca0c54562822af46a241118522

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 93e419ee500a9269317e6a4e48c777c2bf0891f96945f1f78475dd21f0b9604f
MD5 75b302f296819863d103d47d73399b46
BLAKE2b-256 6852dc0b3a17e0f184e27b74c803b7d6f1e568fd7d733192d55a07fe84a24f9f

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2671fa88543c7e5509279e961bf27b672aab776cf4d4527156e8451477e97cf3
MD5 2baea4c2b137341552c9f565c33f3dec
BLAKE2b-256 0ea362ce1b87faa32e56fc147523819d2245883c07c184ae42da013c8870c8b0

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_python-1.145.0-cp312-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for codex_python-1.145.0-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6c2ec2102fd86806f812beea6a67d315cbbed83d36a74880af564561ece59e00
MD5 a5f829b15a73b55b707339117eda1191
BLAKE2b-256 05d72ceab7c5551ed5273274e8901ac9f2561f3acbbe62b314309483d9171017

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.145.0-cp312-abi3-macosx_10_12_x86_64.whl:

Publisher: release-published.yml on gersmann/codex-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.146.0

9 files

This release

1.145.0 This release

9 files

1.141.1

9 files

1.141.0

9 files

1.140.0

9 files

1.131.1

9 files

1.131.0

9 files

1.122.0

9 files

1.114.2

10 files

1.114.1

10 files

1.114.0

10 files

1.0.1

10 files

Yanked

1.0.0

10 files

Yanked reason: mistake

Pre-release

1.0.0b3

10 files

Pre-release

1.0.0b2

10 files

0.3.0

7 files

0.2.16

7 files

0.2.15

7 files

0.2.14

7 files

0.2.13

7 files

0.2.12

7 files

0.2.11

7 files

0.2.10

7 files

0.2.8

7 files

0.2.7

6 files

0.2.3

7 files

0.2.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page