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/{codex|codex.exe}

If the bundled binary is not present, for example in a source checkout, the SDK falls back to codex on PATH.

You can override the executable path with:

  • CodexOptions(codex_path_override=...)
  • codex.app_server.AppServerProcessOptions(codex_path_override=...)

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 7, 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 7, 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.141.1.tar.gz (95.0 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.141.1-cp312-abi3-win_arm64.whl (100.2 MB view details)

Uploaded CPython 3.12+Windows ARM64

codex_python-1.141.1-cp312-abi3-win_amd64.whl (87.0 MB view details)

Uploaded CPython 3.12+Windows x86-64

codex_python-1.141.1-cp312-abi3-musllinux_1_2_x86_64.whl (102.6 MB view details)

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

codex_python-1.141.1-cp312-abi3-musllinux_1_2_aarch64.whl (96.1 MB view details)

Uploaded CPython 3.12+musllinux: musl 1.2+ ARM64

codex_python-1.141.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (102.4 MB view details)

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

codex_python-1.141.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (95.9 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

codex_python-1.141.1-cp312-abi3-macosx_11_0_arm64.whl (92.7 MB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

codex_python-1.141.1-cp312-abi3-macosx_10_12_x86_64.whl (99.8 MB view details)

Uploaded CPython 3.12+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for codex_python-1.141.1.tar.gz
Algorithm Hash digest
SHA256 53971393d3e9a78611712b9c05e7af43d92274d413b09ab65a5bdfe487356060
MD5 74f25931a5b40e69e1e082510fadacb8
BLAKE2b-256 af90c86daffbee44e968cda0b1903870c65a00605bebd9684c535fc2dbbd42d2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 0bc8f32b0f15c3470494bc71b3b1b7aa93f7c8bb3ae36e2ac2166a559376c739
MD5 1667734669147bfc3423f595ccdf4825
BLAKE2b-256 50740d2ed1c2ddc2ab49368aeffed132d53ae1700091b8c44d7c72f0b9e8de87

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 98f48317552c0b3ddf080fe697867954e330eb93b4b4ffba2f72220b1d00ba67
MD5 9f2859bb972b2437adbbecf49c53e5d5
BLAKE2b-256 77f5a9ae7196a3196fa3a648ef98824e0a365e362b9140750e3b72dd96742804

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 953591e6ff83667f4841465f149aac71a5e776f49655c2a309ea627f6ff5eed0
MD5 f2b3e0575ce54ef7bcac86a051ac3128
BLAKE2b-256 0ed8f3dec12f06056b3600d5b9e6aae0a1e34ea00c6100dcb288fe5bf5bcb686

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 2d7ed31d2fbbb2c52e440b4ff2e4465af218fda40d6af08c4dce90668d64d820
MD5 497d9de3ea6ef42651d37bed28dc92c9
BLAKE2b-256 369be8c52f436dca627bb0ed02c49d2da374a37fe9b3d93127b412122c3ede22

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9a20481374abcab21355ec3db84a91a3ffcbc00779c620d57598b8103eded45b
MD5 4ecde3ff3a34d0f774b72e14fd416f0c
BLAKE2b-256 e2e5d930e6be6b6a9e25e709ae0fcd9868c210c6817f2f58a40e758e4b4c13b8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 aa8562b531e3a19895461fe6fc80926c7f8e3ee6723cc5ffbd22e95e58eee1bc
MD5 a73c9eafcd48bf9155ea4f2044937d12
BLAKE2b-256 703a7aa9d2f7454b604fd4129f792f3751adc1f3754a849fb8501d552f5eec9e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9efc5d4b09ad98514a1e4877760a870e48c5683b63907acfeeff216522131fea
MD5 20a43717b0daadbe0bb745cd4b7e5e7b
BLAKE2b-256 865f54da371ea0d6e2911835bfbaa5dccaf13558e581e8ac106f10ff9de0f7fd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_python-1.141.1-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f1f3d5a1358bf3e8d47ffc6a16254e11270e64a8d0245a009391d6e878489e60
MD5 3a3b66f3e6cfe58fcdc4a43c60bffdc4
BLAKE2b-256 a8ee0ed8d227d6b267845c4cd2eb6574c402c2ea99997b23343133d7134f3ee5

See more details on using hashes here.

Provenance

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

1.145.0

9 files

This release

1.141.1 This release

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