codex

name	codex
description	Run headless OpenAI Codex turns over the iii bus — sandboxed shell, file edits, and web search against any host directory — with verbatim event streaming, thread resume, and full SDK option pass-through.

codex

The codex worker exposes the OpenAI Codex API as iii functions. One codex::run call executes one headless Codex turn — the same agent the user runs in their terminal, with the same login, filesystem, and sandbox — in a chosen working directory, and returns the final result and token usage. The worker is a pure pass-through: named payload fields cover the common path, the options field forwards any Codex SDK ThreadOption verbatim, and every thread event mirrors untouched onto the codex::events stream. A translated AgentEvent view lands on agent::events, which is what the iii console renders.

Requires the codex CLI on the host with an existing codex login or OPENAI_API_KEY in the worker environment. When a turn needs a capability beyond Codex itself, add another iii worker to the bus instead of bolting anything onto this one.

When to Use

• Delegate a whole coding task ("add an endpoint and run the tests") in one call, instead of orchestrating individual coder::* / shell::* calls yourself: codex::run with prompt and cwd.
• Continue a conversation across calls: pass the same session_id again and the worker resumes the underlying Codex thread with full context.
• Run long jobs without holding the call open: codex::start returns {session_id, started} immediately; follow codex::events (group_id = session_id) for raw progress or agent::events for the rendered view; interrupt with codex::stop.
• Act on the whole backend: turns carry the iii runtime context by default (delivered as Codex developer_instructions), so the agent discovers and calls any registered function through the iii CLI (engine::functions::list, iii trigger <fn> --help); disable per turn with iii_context: false.
• Plan before touching anything: run the planning prompt with sandbox_mode: read-only (writes physically fail), read the plan, then send "implement the plan" on the same session_id with sandbox_mode: workspace-write.
• Get structured final output: pass output_schema (JSON schema) and the final agent message is JSON matching it.
• Attach screenshots or diagrams: images: ["/path/a.png"] adds local images to the prompt.
• Wire MCP servers or model providers into one turn: codex_config forwards any config.toml override, e.g. {"codex_config": {"mcp_servers": {"github": {"command": "gh-mcp"}}}}.
• Reach past the named payload fields: anything the SDK ThreadOptions accept goes through options unchanged, e.g. {"options": {"networkAccessEnabled": true, "webSearchMode": "live"}}.

Boundaries

• Spawns the host codex CLI per turn — needs Codex installed and authenticated; not available inside a bare container without it.
• Execution safety is Codex's own sandbox (sandbox_mode), not the engine's: read-only blocks writes, workspace-write allows edits in cwd, danger-full-access disables the sandbox. Headless turns run approval_policy: never, so blocked commands fail instead of prompting.
• One turn per session at a time: check codex::status (live: true) before sending another codex::run for the same session_id; parallel runs against one session race on the underlying thread resume.
• agent::events carries whole-message frames; per-item progress detail (command output as it accumulates, todo lists) exists only on codex::events.

Functions

• codex::run — run one Codex turn and wait; accepts prompt (or a messages array whose last user entry becomes the prompt), plus model, cwd, sandbox_mode, approval_policy, reasoning_effort, skip_git_repo_check, output_schema, and raw options; returns {session_id, codex_thread_id, result, stop_reason, usage}.
• codex::start — same payload, returns {session_id, started} immediately; progress arrives on the streams.
• codex::stop — interrupt the live run for a session.
• codex::status — point-in-time session view: live flag, status, turns, usage.
• codex::sessions::list — every session this worker has run.