Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

docs / external-sdks

External SDKs

Overview

The sdk/** tree ships external SDK surfaces for Codex in TypeScript and Python, plus a Python runtime wheel that carries the pinned Codex CLI binary. The two SDKs expose different transport layers:

  • sdk/…/index.ts exports the TypeScript public API: Codex, Thread, event and item unions, and option types. sdk/…/codex.ts is a small facade that creates or resumes Thread instances.
  • sdk/…/thread.ts implements run() and runStreamed(). It normalizes string or structured text/local-image input, writes turn output schemas through sdk/…/outputSchemaFile.ts, invokes CodexExec, parses JSONL events, stores the thread id from thread.started, and collects final results from item.completed and turn.completed events.
  • sdk/…/exec.ts is the TypeScript runtime bridge. It resolves the installed @openai/codex platform package, finds the native codex binary under package-layout or legacy vendor paths, prepends bundled codex-path directories to PATH, then spawns codex exec --experimental-json with CLI flags derived from CodexOptions, ThreadOptions, and TurnOptions. sdk/…/events.ts and sdk/…/items.ts are hand-written protocol types based on codex-rs/…/exec_events.rs, not generated files.
  • sdk/…/__init__.py exports the Python public API: sync/async high-level clients, thread and turn handles, input dataclasses, sandbox and approval enums, low-level config, errors, and retry helpers. sdk/…/api.py is the high-level sync/async facade over the app-server protocol, with generated public method blocks for thread lifecycle and turn options.
  • sdk/…/client.py is the synchronous JSON-RPC transport for codex app-server --listen stdio://. It resolves the binary either from CodexConfig.codex_bin or the openai-codex-cli-bin runtime package, starts the process, sends newline-delimited JSON-RPC requests, handles server-to-client approval requests, drains stderr for transport errors, and exposes typed methods such as thread/start, turn/start, account/login/start, model/list, and goal operations.
  • sdk/…/async_client.py wraps the synchronous client with asyncio.to_thread, a bounded turn-start executor, and cancellation cleanup so async API users do not block the event loop while the single stdio transport remains owned by the sync client.
  • sdk/…/_message_router.py is the Python SDK's central demultiplexer. The reader thread is the only stdout consumer; it routes JSON-RPC responses by id, login notifications by login id, turn notifications by turn id, global notifications, and logical goal-operation notifications.
  • sdk/…/v2_all.py and sdk/…/notification_registry.py are checked-in generated protocol artifacts for the Rust app-server protocol. sdk/…/pyproject.toml points codegen at ../../codex-rs/app-server-protocol/schema/json, and sdk/…/update_sdk_artifacts.py normalizes those schemas, runs datamodel-code-generator, builds notification routing metadata, regenerates public API blocks in api.py, and stages release artifacts.
  • sdk/…/__init__.py exposes bundled_codex_path(), bundled_package_dir(), and bundled_path_dir() for the runtime package. sdk/…/pyproject.toml includes the packaged bin/**, codex-resources/**, and codex-path/**; sdk/…/hatch_build.py marks wheels as platform-specific and rejects source distributions.

Python input and behavior helpers sit beside the clients: sdk/…/_inputs.py maps public TextInput, ImageInput, LocalImageInput, SkillInput, MentionInput, and ExternalMessage into app-server wire input/tool-output payloads; _approval_mode.py and _sandbox.py translate public enums into generated protocol values; _login.py wraps browser and device-code login flows; _goal.py coalesces runtime-generated physical goal turns into one logical turn stream; _run.py collects streamed turn notifications into a TurnResult; _runtime_requirements.py gates newer SDK fields against a minimum CLI version or an unversioned checkout's generated schemas; errors.py maps JSON-RPC errors into typed SDK exceptions; models.py and types.py provide stable public model exports around generated protocol types.

Build and release tooling is split by package. sdk/…/package.json, sdk/…/tsup.config.ts, sdk/…/tsconfig.json, sdk/…/jest.config.cjs, sdk/…/eslint.config.js, .prettierrc, and .prettierignore define an ESM Node 18 package built by tsup, tested by Jest/ts-jest, and linted/formatted with ESLint and Prettier. sdk/…/pyproject.toml, sdk/…/uv.lock, sdk/python/BUILD.bazel, sdk/…/release_version.py, and sdk/…/_runtime_setup.py define the Python SDK package, pinned dependency on openai-codex-cli-bin, schema export integration, version normalization, and local runtime bootstrapping from GitHub release assets. sdk/…/pyproject.toml, sdk/…/uv.lock, sdk/…/hatch_build.py, and sdk/…/README.md define the wheel-only runtime package.

Tests and examples are part of the shipped SDK area. sdk/typescript/tests/** covers spawn argument construction, output schema forwarding, abort behavior, MCP conformance gates, and mock Responses API flows; sdk/typescript/samples/** and sdk/…/README.md demonstrate streaming and structured output. sdk/python/tests/** covers generated-contract drift, public signatures, runtime package staging, app-server integration, notification routing, async behavior, approvals, login, inputs, streaming, and goal operations; sdk/python/examples/**, sdk/python/docs/**, sdk/python/notebooks/sdk_walkthrough.ipynb, sdk/…/README.md, and sdk/…/RELEASING.md are user-facing examples, docs, walkthroughs, and release notes for the Python SDK.

Path routing under sdk/** should be assigned as follows: sdk/typescript/src/** is TypeScript SDK runtime and API code; sdk/typescript/tests/** is TypeScript SDK validation; sdk/typescript/samples/** plus TypeScript README/config files are TypeScript package docs and tooling; sdk/python/src/openai_codex/** is Python SDK runtime, generated protocol, and API code; sdk/python/scripts/**, sdk/python/BUILD.bazel, sdk/…/pyproject.toml, sdk/…/uv.lock, sdk/…/release_version.py, and sdk/…/_runtime_setup.py are Python SDK generation/build/release tooling; sdk/python/tests/** is Python SDK validation; sdk/python/examples/**, sdk/python/docs/**, sdk/python/notebooks/**, sdk/…/README.md, and sdk/…/RELEASING.md are Python SDK user docs/examples; sdk/python-runtime/** is the separate runtime-binary package consumed by the Python SDK.

Coupling

Risks