open-codex-bridge

Python facade for running Codex app-server sessions and sharing their live conversation state over the Codex IPC owner/follower protocol.

On macOS and Linux, the bridge first joins the current desktop router at $CODEX_HOME/ipc/ipc.sock. It falls back to the older $TMPDIR/codex-ipc/ipc-{uid}.sock endpoint only when that compatibility socket is already active and passes the desktop ownership checks.

Library usage

from pathlib import Path

from codex_bridge import CodexIpcConfig, CodexIpcSession


async def main() -> None:
    config = CodexIpcConfig(
        codex_bin=Path("/opt/homebrew/bin/codex"),
        host_id="local",
        model="gpt-5.4",
        reasoning_effort="high",
    )

    async with CodexIpcSession(config) as session:
        thread = await session.start_new_thread()
        print(f"started {thread.id}")

        async for state in session.watch_state():
            # Forward this raw conversation state to a browser over WebSocket.
            print(state)


async def resume_existing(thread_id: str) -> None:
    async with CodexIpcSession(CodexIpcConfig(thread_id=thread_id)) as session:
        await session.hydrate_initial_state()
        await session.run_prompt("Summarize the current repo", wait_for_completion=True)

If codex_bin is omitted, the Codex SDK uses its pinned runtime resolver. Pass an openai_codex.CodexConfig as codex_config when you need full control over app-server launch arguments.

SSH app-server

SSH websocket transport is an open-codex-bridge extension, not part of the official openai-codex SDK:

from codex_bridge import (
    AppServerConfig,
    CodexIpcConfig,
    SshConnectionConfig,
    SshWebsocketAppServerConfig,
)

config = CodexIpcConfig(
    codex_config=AppServerConfig(
        ssh_websocket=SshWebsocketAppServerConfig(
            connection=SshConnectionConfig(host="builder.example.com"),
            remote_cwd="/srv/project",
        )
    )
)

The older app_server_config argument remains available as a compatibility alias for existing consumers.

TUI demo

The TUI is a development tool and is kept out of the core dependency set:

uv run --extra tui python examples/demo.py --codex-bin /opt/homebrew/bin/codex

Core imports such as import codex_bridge do not require textual, rich, or pillow.