Skip to main content

Codexed

PyPI License Package status Monthly downloads Distribution format Wheel availability Python version Implementation Releases Github Contributors Github Discussions Github Forks Github Issues Github Issues Github Watchers Github Stars Github Repository size Github last commit Github release date Github language count Github commits this month Package status PyUp

Read the documentation!

Typed, async Python client for the Codex app-server JSON-RPC protocol. codexed starts codex app-server as a subprocess (or connects to a remote one via WebSocket), lets you create and resume threads, run turns and stream every server notification as a pydantic model.

Installation

pip install codexed
# WebSocket transport for remote app-servers
pip install "codexed[websocket]"

The codex CLI must be installed and logged in for the default subprocess transport.

Quickstart

import asyncio

from codexed import CodexClient, ItemAgentMessageDeltaNotification, TurnCompletedEvent


async def main() -> None:
    async with CodexClient() as client:
        session = await client.thread_start(cwd=".")
        async for event in session.turn_stream("Summarize this repository"):
            match event:
                case ItemAgentMessageDeltaNotification(params=params):
                    print(params.delta, end="", flush=True)
                case TurnCompletedEvent():
                    print()


asyncio.run(main())

Events are a discriminated union (codexed.CodexEvent) keyed on the JSON-RPC method; each event's payload lives in .params. turn_stream ends after TurnCompletedEvent and raises TurnFailedError when the server reports an error.

Structured output

from pydantic import BaseModel


class FileList(BaseModel):
    files: list[str]
    total: int


async with CodexClient() as client:
    session = await client.thread_start(cwd=".")
    result = await session.turn_stream_structured("List the Python files", FileList)
    print(result.files)

MCP servers, tools and approvals

from codexed import CodexClient, HttpMcpServer, StdioMcpServer
from codexed.models.tool_config import ShellToolConfig, WebSearchToolConfig

mcp_servers = {
    "docs": HttpMcpServer(url="http://localhost:8000/mcp"),
    "fs": StdioMcpServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem"]),
}

async with CodexClient(mcp_servers=mcp_servers) as client:
    client.set_auto_approve()  # or pass on_approval=... / on_user_input=... to CodexClient
    session = await client.thread_start(
        cwd=".",
        tools=[ShellToolConfig(), WebSearchToolConfig()],  # [] disables all builtin tools
    )

Remote app-server

from codexed import CodexClient, WebSocketTransport

transport = WebSocketTransport("ws://localhost:4500", auth_token="...")
async with CodexClient(transport=transport) as client:
    models = await client.model_list()

Features

  • Full thread lifecycle: thread_start, thread_resume, thread_fork, thread_list, plus per-thread Session operations (steer, interrupt, review, revert, compact, rename, archive, inject items, MCP tool calls and resource reads).
  • Streaming events as typed pydantic models, token usage tracking (session.usage), and listeners for events outside a turn (client.add_event_listener).
  • Structured output via pydantic models (turn_stream_structured).
  • Programmatic MCP server injection (global or per thread) and builtin tool configuration.
  • Server-request handlers for command/file-change/skill approvals, user input, dynamic tool calls and MCP elicitation.
  • Sub-APIs for account and rate limits (client.account), file system (client.fs), skills, plugins and marketplace, config read/write, models, apps and experimental features.
  • Realtime sessions (session.realtime(...)).
  • Protocol models generated from the Codex app-server JSON schema, JSON-RPC errors mapped to exceptions (CodexRequestError, ServerBusyError, ..., is_retryable_error).

License

MIT

Metadata

Release files for codexed 1.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codexed 1.3.2
File Size Uploaded Provenance Actions
codexed-1.3.2.tar.gz 120.9 kB With provenance Details for codexed-1.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codexed 1.3.2
File Interpreter ABI Platform Actions
codexed-1.3.2-py3-none-any.whl Python 3 none any Details for codexed-1.3.2-py3-none-any.whl

Total release size: 249.7 kB

Release files / codexed-1.3.2.tar.gz

Download URL codexed-1.3.2.tar.gz
Size 120.9 kB
Tags Source
SHA-256 checksum
How to use checksums
98817f649925933448b0ff2bc3364a5821db672e7614a3fe50a00e32e1a0b638
BLAKE2b-256 checksum
How to use checksums
0a7599594dbf80f6eb9b8adbb58d3ab308e93eecc38b89e714724cfcfe4d4df7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Release files / codexed-1.3.2-py3-none-any.whl

Download URL codexed-1.3.2-py3-none-any.whl
Size 128.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d8fb6913c9c851d0e6513fd49c5ffdf83cc665a5b07110fcf52a5b6bcac73d0c
BLAKE2b-256 checksum
How to use checksums
c0fc1224a71e4e10817113a4bf61ec47abc7cf183448ea042baededae81160af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Security for codexed 1.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for codexed-1.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page