skip to content
iii / worker
$registry / workers

codex

v0.1.20

OpenAI Codex as an iii worker; codex::run/start/stop/status/sessions::list spawn the codex CLI for headless turns, deliver raw thread events on the codex::raw-event trigger type and AgentEvent frames on codex::agent-event.

worker
iiiverified
81 installs0 in 7d0 today
install
$iii trigger compose::add worker=codex
binarylicense: Apache-2.0agentcodex-clicoding-agentheadlessopenai
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64
6functions2triggers1skills0depsv0.1.20version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

6

codex::on-config-change

function

Internal: reload codex configuration when it changes.

request
empty object
response
  • okboolean

codex::run

function

Run a Codex coding-agent turn and wait for its result. Accepts `prompt` or a `messages` array plus a `codex_config` pass-through; delivers raw Codex events on codex::raw-event and AgentEvent frames on codex::agent-event, and returns {session_id, result, usage}.

request
  • additional_directoriesstring[]

    Additional writable directories alongside the working root (--add-dir).

  • approval_policystring

    Codex approval policy; headless callers leave it at never.

  • codex_configunknown

    Codex config.toml overrides for this turn (e.g. mcp_servers, model_providers, profiles).

  • cwdstring

    Working directory the turn runs in.

  • iii_contextboolean

    Inject the iii runtime discovery prompt as developer_instructions (default true via config).

  • imagesstring[]

    Paths to local images attached to the prompt.

  • messagesobject[]

    Alternative to prompt: role/content messages; the last user entry becomes the prompt.

    • contentunknownrequired

      Either a plain string or an array of content blocks.

    • rolestringrequired
  • modelstring

    Model id; empty = Codex default.

  • output_schemaunknown

    JSON schema for structured final output.

  • promptstring

    The user prompt for this turn.

  • reasoning_effortstring

    Model reasoning effort: minimal | low | medium | high | xhigh.

  • sandbox_modestring

    Codex sandbox mode: read-only | workspace-write | danger-full-access.

  • session_idstring

    iii session id; reuse to resume the same Codex thread.

  • skip_git_repo_checkboolean

    Allow running outside a git repository.

  • timeout_msinteger· uint64min 0

    Reserved for callers; not forwarded.

response
  • busyboolean
  • codex_thread_idstring
  • is_errorboolean
  • num_turnsinteger
  • reasonstring
  • resultstring
  • session_idstring
  • stop_reasonstring
  • usageobject

codex::sessions::list

function

List every Codex session this worker has run.

request
empty object
response
  • sessionsobject[]
    empty object

codex::start

function

Start a Codex turn and return immediately; bind codex::agent-event (or codex::raw-event) with { session_id } for progress and turn_end, or poll codex::status.

request
  • additional_directoriesstring[]

    Additional writable directories alongside the working root (--add-dir).

  • approval_policystring

    Codex approval policy; headless callers leave it at never.

  • codex_configunknown

    Codex config.toml overrides for this turn (e.g. mcp_servers, model_providers, profiles).

  • cwdstring

    Working directory the turn runs in.

  • iii_contextboolean

    Inject the iii runtime discovery prompt as developer_instructions (default true via config).

  • imagesstring[]

    Paths to local images attached to the prompt.

  • messagesobject[]

    Alternative to prompt: role/content messages; the last user entry becomes the prompt.

    • contentunknownrequired

      Either a plain string or an array of content blocks.

    • rolestringrequired
  • modelstring

    Model id; empty = Codex default.

  • output_schemaunknown

    JSON schema for structured final output.

  • promptstring

    The user prompt for this turn.

  • reasoning_effortstring

    Model reasoning effort: minimal | low | medium | high | xhigh.

  • sandbox_modestring

    Codex sandbox mode: read-only | workspace-write | danger-full-access.

  • session_idstring

    iii session id; reuse to resume the same Codex thread.

  • skip_git_repo_checkboolean

    Allow running outside a git repository.

  • timeout_msinteger· uint64min 0

    Reserved for callers; not forwarded.

response
  • session_idstring
  • startedboolean

codex::status

function

Check the status of one Codex session.

request
  • session_idstringrequired

    iii session id returned by codex::run / codex::start.

response
  • liveboolean
  • recordobject
  • session_idstring

codex::stop

function

Interrupt a live Codex run for a session.

request
  • session_idstringrequired

    iii session id returned by codex::run / codex::start.

response
  • reasonstring
  • session_idstring
  • stoppedboolean

triggers

2

codex::agent-event

trigger

Translated AgentEvent frames of one codex session. Config: { session_id, metadata? }. Payload: { session_id, event_id, seq, epoch, source, event }. Ephemeral (not stored, not replayed); order by (epoch, seq).

invocation
valueunknown
return
valueunknown

codex::raw-event

trigger

Raw Codex thread events (codex exec --json lines, verbatim) of one codex session. Config: { session_id, metadata? }. Payload: { session_id, event_id, seq, epoch, source, event }. Ephemeral (not stored, not replayed); order by (epoch, seq).

invocation
valueunknown
return
valueunknown