DocsUseful ToolsCodex

codex

Drive OpenAI's Codex CLI via its native app-server protocol — session resume, live step streaming, and per-action approval.

Download

Installation

Requires the codex CLI and Codex auth:

code
bash
npm install -g @openai/codex
codex login   # or your usual Codex auth flow

Set $CODEX_CMD to override the binary path/command if needed.

Quick Start

main.py
python
from connectonion import Agent
from connectonion.useful_tools import codex

agent = Agent("architect", tools=[codex])
agent.input("Ask Codex to fix the failing tests in ./myrepo")

Why app-server

ConnectOnion drives Codex's built-in app-server (OpenAI's native JSON-RPC 2.0 protocol) directly from Python — our own client is the adapter, so the only dependency is the codex binary itself, no external Node adapter.

This gets you session + resume (thread/start, thread/resume), live streaming of Codex's inner steps, and per-action approval — the server asks before each sensitive step, which maps onto agent.io.request_approval.

API

main.py
python
codex(
    prompt: str = "",                # Omit to open a thread without submitting a turn
    session_id: str = "",            # Thread id from a previous call, to resume it
    cwd: str = "",                   # Directory Codex works in (default: cwd)
    sandbox: str = "workspace-write",  # "read-only" | "workspace-write" | "danger-full-access"
    model: str = "",                 # Codex model override (e.g. "gpt-5-codex"); empty = default
    timeout: int = 600,              # Seconds before timeout
    approval: str = "manual",        # "manual" (ask via agent.io) or "auto" (approve automatically)
) -> str  # JSON envelope

With no frontend to ask, manual approval denies each request rather than escalating.

With an empty prompt, the adapter initializes and creates or resumes the native thread, returns its session ID with opened: true, and does not call account/read orturn/start. Because Codex persists a rollout only after the first turn, a new open-only app-server remains alive in a bounded, expiring registry so the first Work Room message uses that exact session ID.

Native Route and Work Room

In co ai, an explicit request to run, use, start, open, or ask Codex always targets this adapter. Executable Codex commands hidden in shell chains, command substitutions, package runners, or background wrappers are rejected before approval and process creation. Searches and prose that only mention Codex are not blocked.

O Chat renders the parent invocation immediately. Open Work Room shows the provider conversation, correlated activity, and files; approvals, Stop, failure, completion, reconnect, and return-to-parent all use the same authenticated OIP session. The Codex-targeted composer remains visible throughout that lifecycle; when the current state cannot accept input, it is disabled with an explicit reason rather than turning Work Room into a read-only status page.

Return Value

A JSON string envelope:

code
json
{
  "provider": "codex",
  "session_id": "<thread id>",
  "resumed": false,
  "last_message": "...",
  "usage": { /* token/cost info, if reported */ },
  "exit_code": 0
  // "error": "..." — present only when something went wrong
}

Resuming a Session

main.py
python
import json
from connectonion.useful_tools import codex

result = json.loads(codex("Start refactoring the auth module"))
session_id = result["session_id"]

# Later, continue the same Codex thread
result2 = json.loads(codex("Now add tests for it", session_id=session_id))
print(result2["resumed"])  # True

Approval Modes

Mode	Behavior
manual	Default. Asks the human via `agent.io`, rendered as an approval card. With no frontend attached, requests are denied rather than escalated.
auto	Approves every request automatically — no human in the loop.

Sandbox Levels

Value	Meaning
read-only	Codex can inspect the codebase but not write to it
workspace-write	Default. Codex can edit files inside the working directory
danger-full-access	No sandbox restrictions — use with caution

Frontend Contract

Codex's inner steps are streamed as the same OIP events the connection layer bundled in @connectonion/react maps to chat items — a parent provider_invocation plus correlated tool_call and tool_result activity. Older clients retain the generic tool-card fallback.