Skip to content
Sign in

codex

v0.2.0

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 codex::on-raw-event and AgentEvent frames on codex::on-agent-event, observed per session.

license: Apache-2.0Used in 1 kitagentcodex-clicoding-agentheadlessopenai

Install

bash
iii trigger compose::add worker=codex@0.2.0

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions8

codex::on-agent-event

Function

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

Request
  • epochstringrequired

    Per-process uuid; a restart starts a new epoch.

  • eventunknownrequired

    The frame, unchanged.

  • event_idstringrequired

    `<session_id>-<epoch>-<seq:08>`: dedup key.

  • seqinteger· uint64requiredmin 0

    Contiguous per (feed, session, epoch), from 0.

  • session_idstringrequired
  • sourcestringrequired

    The producing worker.

Response
  • epochstringrequired

    Per-process uuid; a restart starts a new epoch.

  • eventunknownrequired

    The frame, unchanged.

  • event_idstringrequired

    `<session_id>-<epoch>-<seq:08>`: dedup key.

  • seqinteger· uint64requiredmin 0

    Contiguous per (feed, session, epoch), from 0.

  • session_idstringrequired
  • sourcestringrequired

    The producing worker.

codex::on-config-change

Function

Internal: reload codex configuration when it changes.

Request
Empty object
Response
  • okboolean

codex::on-raw-event

Function

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

Request
  • epochstringrequired

    Per-process uuid; a restart starts a new epoch.

  • eventunknownrequired

    The frame, unchanged.

  • event_idstringrequired

    `<session_id>-<epoch>-<seq:08>`: dedup key.

  • seqinteger· uint64requiredmin 0

    Contiguous per (feed, session, epoch), from 0.

  • session_idstringrequired
  • sourcestringrequired

    The producing worker.

Response
  • epochstringrequired

    Per-process uuid; a restart starts a new epoch.

  • eventunknownrequired

    The frame, unchanged.

  • event_idstringrequired

    `<session_id>-<epoch>-<seq:08>`: dedup key.

  • seqinteger· uint64requiredmin 0

    Contiguous per (feed, session, epoch), from 0.

  • session_idstringrequired
  • sourcestringrequired

    The producing worker.

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::on-raw-event and AgentEvent frames on codex::on-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; observe codex::on-agent-event (or codex::on-raw-event) with args { 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

Search the registry

Find workers, kits and executables, or jump to a page.