codex-client 0.0.3

Claude Code SDK-style wrapper around the Codex CLI for programmatic automation.

Codex Client (Unofficial)

Codex Client is a lightweight, community-maintained Python wrapper around the Codex CLI. It lets you launch chats, stream reasoning and tool events, and drive MCP servers from your own applications—similar to how the claude-code-sdk works for Anthropics' Claude tools, but tailored for Codex.

This package is not an official OpenAI release. Expect the API surface to evolve as the Codex CLI changes.

Installation

# clone this repository, then install in a virtual environment
pip install codex-client
# or, if you use uv
uv pip install codex-client

Ensure the codex executable is on your PATH, since the client shells out to codex mcp serve under the hood.

Authentication quick start

The bundled CLI wraps the official Codex login helper so you can capture and reuse credentials safely.

# Launch the Codex login flow, witness the browser open, and wait for success
codex-client login

# Prefer to launch the browser yourself? Pass --no-browser and follow the prompt
codex-client login --no-browser

# See the stored payload (compressed base64) and copy it to another machine
codex-client read

# Import the copied payload into a fresh environment
codex-client set "<payload>"

# Clear local credentials when finished
codex-client logout

On the receiving machine you can also drop straight into Python:

from codex_client.auth import CodexAuth

auth = CodexAuth(codex_command="codex-client")
auth.set("<payload-from-read>")
# later, confirm or refresh as needed
token = auth.read()

Core Concepts

• Client lifecycle – codex_client.Client manages the background MCP session. Use it as an async context manager to guarantee clean startup and teardown.
• Chats – codex_client.Chat represents an ongoing conversation. Iterate over it for raw events, call await chat.get() for the final assistant reply, and await chat.resume(...) to continue the dialogue.
• Configuration – CodexChatConfig, CodexProfile, and CodexMcpServer (in codex_client.config) serialize options Codex expects: models, sandboxing, approval policy, working directory, environment overrides, MCP servers, and more.
• Structured streaming – Helpers in codex_client.structured (structured, AssistantMessageStream, ReasoningStream, CommandStream) aggregate low-level deltas into convenient async streams.
• Events & errors – All event dataclasses live in codex_client.event; exceptions (CodexError, ChatError, ToolError, etc.) live in codex_client.exceptions so you can handle failures precisely.

Usage Example

import asyncio
from codex_client import (
    Client,
    CodexChatConfig,
    CodexProfile,
    CodexMcpServer,
    ReasoningEffort,
    SandboxMode,
    Verbosity,
)
from codex_client.structured import structured, AssistantMessageStream, ReasoningStream, CommandStream

async def run(prompt: str) -> None:
    config = CodexChatConfig(
        profile=CodexProfile(
            model="gpt-5",
            reasoning_effort=ReasoningEffort.MINIMAL,
            verbosity=Verbosity.HIGH,
            sandbox=SandboxMode.DANGER_FULL_ACCESS,
        ),
        mcp_servers=[
            CodexMcpServer(
                name="context7",
                command="npx",
                args=["-y", "@upstash/context7-mcp", "--api-key", "<api_key>"]
            )
        ],
    )

    async with Client() as client:
        chat = await client.create_chat(prompt, config=config)

        async for event in structured(chat):
            if isinstance(event, AssistantMessageStream):
                async for chunk in event.stream():
                    print(chunk, end="", flush=True)
                print("\n[assistant message complete]")
            elif isinstance(event, ReasoningStream):
                async for chunk in event.stream():
                    print(f"[reasoning] {chunk}")
            elif isinstance(event, CommandStream):
                async for chunk in event.stream():
                    if chunk.text:
                        print(f"[command {event.command}] {chunk.text}")

        final_reply = await chat.get()
        print("Final reply:", final_reply)

        await chat.resume("Thanks! Any closing thoughts?")

asyncio.run(run("Introduce yourself."))

This pattern illustrates how to:

• Bootstrap a Codex profile, sandbox policy, and optional MCP servers.
• Open a chat, stream assistant output, reasoning traces, and command execution in real time.
• Retrieve the final assistant response and continue the conversation with chat.resume().

Extending Codex Client

• Inject your own MCP servers or tools by modifying the CodexChatConfig you pass to Client.create_chat.
• Capture richer telemetry (token counts, command durations, event payloads) by iterating the raw chat events instead of the structured helper.
• Integrate Codex Client into automation (FastAPI endpoints, Slack bots, GitHub Actions) so Codex handles the heavy lifting while you orchestrate workflows.

Bug reports and contributions are welcome—the codebase stays intentionally small so you can adapt it quickly.