Codex SDKs

The official TypeScript and Python SDKs plus community Go packages — and the distinction that matters: wrapping the CLI versus speaking to the app-server.

Last reviewed 2026-08-04 · verified against the pingdotgg/t3code repo

Two official SDKs, several community ones. The important distinction between them isn't language — it's whether they wrap the CLI or speak to the app-server directly, because that decides what you can reach.

Official SDKs#

npm install @openai/codex-sdk
pip install openai-codex

What both SDKs give you#

• Start new threads programmatically
• Continue a conversation on an existing thread
• Resume a previous thread by id
• Sandbox presets: read-only, workspace-write, full-access
• Per-turn filesystem access control

The TypeScript SDK additionally supports streaming, structured output with Zod schemas, thread resumption and image attachments. It spawns the CLI and exchanges JSONL events over stdin/stdout.

Python, minimal example#

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    result = thread.run("Make a plan to diagnose and fix CI failures")
    print(result.final_response)

Note the sandbox preset is set at thread start. Choose deliberately — Sandbox.full_access on a CI runner with cloud credentials is the kind of decision worth making consciously rather than by copy-paste. The same reasoning as runtime modes applies.

Community Go SDKs#

No official Go SDK. Four community packages exist, and they differ in a way that matters more than their APIs:

The distinction that actually matters#

CLI wrappers spawn codex and parse its output. Simple, but limited to what the CLI exposes.

App-server clients speak JSON-RPC directly and reach APIs the CLI never surfaces — model listing, thread enumeration, plugin management, per-item streaming, the approval flow.

If you've hit a wall with a CLI wrapper because you couldn't enumerate threads or handle approvals properly, that's the ceiling you found. Moving to an app-server client removes it.

Which should you use?#

Default to an official SDK. They're maintained by the people who ship Codex, and version skew with the CLI is a real and recurring source of breakage. An official SDK that pins its runtime removes an entire class of that.

Rolling your own#

The protocol is JSON-RPC 2.0 over stdio. Any language that can spawn a process and read lines can be a client. Two things save real time:

# generate types matching your exact Codex version
codex app-server generate-ts --out DIR
codex app-server generate-json-schema --out DIR

Do not hand-write these. The schema changes between releases, and generated artifacts are the only way to keep a client honest about which version it targets.

Also remember the wire quirk: the "jsonrpc": "2.0" field is omitted, which breaks strict JSON-RPC libraries. Protocol details →

FAQ#

Is there an official Codex Python SDK?#

Yes. Install it with pip install openai-codex. It requires Python 3.10 or newer and bundles a pinned Codex CLI runtime dependency.

What is the Codex SDK package on npm?#

@openai/codex-sdk, installed with npm install @openai/codex-sdk. It requires Node.js 18+ and is server-side only.

Is there a Go SDK for the Codex app server?#

Not an official one. Several community packages exist, including pmenglund/codex-sdk-go and hishamkaram/codex-agent-sdk-go, which spawn the app-server and speak JSON-RPC directly. Check their activity before depending on one.

What's the difference between a CLI wrapper and an app-server client?#

A CLI wrapper spawns codex and parses its output, limited to what the CLI exposes. An app-server client speaks JSON-RPC directly and can reach model listing, thread enumeration, plugin management and the approval flow.

Can I write a Codex client in a language with no SDK?#

Yes. The app-server is JSON-RPC 2.0 over stdio, so any language that can spawn a process and read lines works. Generate types for your target version with codex app-server generate-json-schema.