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 30, 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:
Latest release

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 30, 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.146.0.tar.gz (105.6 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.146.0-cp312-abi3-win_arm64.whl (97.0 MB view details)

Uploaded CPython 3.12+Windows ARM64

codex_python-1.146.0-cp312-abi3-win_amd64.whl (84.1 MB view details)

Uploaded CPython 3.12+Windows x86-64

codex_python-1.146.0-cp312-abi3-musllinux_1_2_x86_64.whl (98.7 MB view details)

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

codex_python-1.146.0-cp312-abi3-musllinux_1_2_aarch64.whl (93.0 MB view details)

Uploaded CPython 3.12+musllinux: musl 1.2+ ARM64

codex_python-1.146.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (98.5 MB view details)

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

codex_python-1.146.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (92.9 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

codex_python-1.146.0-cp312-abi3-macosx_11_0_arm64.whl (89.5 MB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

codex_python-1.146.0-cp312-abi3-macosx_10_12_x86_64.whl (95.7 MB view details)

Uploaded CPython 3.12+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for codex_python-1.146.0.tar.gz
Algorithm Hash digest
SHA256 f80f75d808ff92d23161c05729590f0a862ddbdc68d43d4af30fabf854be2f57
MD5 7448e28ad00072ee99e6cedeaf2ee686
BLAKE2b-256 b74dfe9381b44f7876dd0f3680bf92a6887f9a52454e7b0e8c61f8da6519c481

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 35cd4eed3be7853b84b339eaddb6c07fea45f3f7e8c661e8d1fbda902067e7f2
MD5 f638693583712fc1f2eebabeb41bdabc
BLAKE2b-256 5178c9434f6a884690664f1b0f34f18359384a709dd80594d3c94ca1d6f55958

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d4fce2c53e38f7c1953e3c8810e0e27b49b68f65fcd0ce2f19f821a917d3a267
MD5 90a72637c81740b6773c79493ae114fe
BLAKE2b-256 49fa6ae5c3a60615441a81fa32196c3fa8f8f46037c9fec1637c3e6ede3e9286

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 63e5339a9aa9410adbd4b88a100940838ec0cd01cdcae01758ad34df2b48954d
MD5 91045dd389269f66ae9eec3b120a402c
BLAKE2b-256 219f2aab4bb849a146a7d88bffe2bb39e7a029f0d8781dbc42aba6a6e9c3e926

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 66c1603ee036d04622f9e427cb0c437db018dfbcefac045ec0cfefda9eb01d63
MD5 afcbf3b2d5a4d3d7b623c75a207a5f42
BLAKE2b-256 f70da6ee807c0768a7f8c146cec41e7de2b40b4d4f7982eccecc9a56a61fe543

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3df619990c1a154d05dfb56b601b7938ebd8137093e06f98a7c0fda63ffcbcf1
MD5 da2f595375e3374455fdc378c5c101e4
BLAKE2b-256 bb379790ce16e3cc366e91493f96a099caa11855b164ee11bb1bfb676c056421

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 7bd11a1089235ffc99dca7513d5a8e258ec6aac330b3636ae3641c27101e5d6c
MD5 d98d926474186ae5a3e7145304e3286d
BLAKE2b-256 7b3e211193aa09b1d0efc2b72da22743d0848362552646e14c4f99291cdb134a

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b709224340935246fdaacbb41d3d26efeecbf4c76f4f586681ed4f11839d14af
MD5 90184522060337d57c942265ff8f9c3b
BLAKE2b-256 85ead5c4685c66fc407c98e9306975f273b44b9ba08bcabb8b7c453c06f745ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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.146.0-cp312-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for codex_python-1.146.0-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9c6f8ffa32acd8a1fce8838b3cb4fa9dd4b8817e0967facf7c93b429492bca1e
MD5 6312df779ddea542241796e8f8540c67
BLAKE2b-256 76ba5a09aeea45cd5a1f76bca2617d0ec8d900518c89b8895a57fe3710c7cf2c

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_python-1.146.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

This release

1.146.0 This release

9 files

1.145.0

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