# Codex

> 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.

- Skill: `iii-hq/codex` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iii-hq/codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iii-hq/codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iii-hq (https://skillmd.com/u/iii-hq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iii-hq/codex

---


# 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.