skip to content
iii / worker
$worker

codex

v0.1.7

OpenAI Codex as an iii worker; codex::run/start/stop/status/sessions::list spawn the codex CLI for headless turns, mirror raw thread events onto codex::events, and stream AgentEvent frames onto agent::events.

iiiverified
44 installs3 in 7d1 today
install
$iii worker add codex
binarycoding-agentopenaicodex-cliheadlessagent
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86
6functions0triggers1skills0depsv0.1.7version
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 one Codex turn and wait for the result. Accepts `prompt` or a `messages` array plus a raw SDK `codex_config` pass-through; streams raw Codex events onto codex::events, AgentEvent frames onto agent::events, 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; watch codex::events / agent::events (group_id = session_id) for progress and turn_end.

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

Point-in-time status of a 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

0
no triggers registered