Codex CLI Runtime

Codex Runtime

Use the installed Codex companion from Claude Code. The caller owns routing and review; the companion performs one bounded task.

Preamble

Resolve the helper from the active plugin first, then the stable marketplace installation:

if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/scripts/codex-companion.mjs" ]; then
  COMPANION="$CLAUDE_PLUGIN_ROOT/scripts/codex-companion.mjs"
else
  COMPANION="$HOME/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs"
fi
[ -f "$COMPANION" ] && echo "CODEX_COMPANION: $COMPANION" || echo "CODEX_COMPANION: missing"

CODEX_COMPANION: missing → stop and report the missing runtime. Do not guess a versioned cache path.

Authority contract

• Resolve the active workspace authority contract before launch. It governs read/write mode, credentials, external actions, production changes, destructive operations, and human gates.
• Include the exact contract in any delegated prompt that may reach those surfaces; a child runtime may not inherit it automatically.
• Without a workspace contract, omit --write, keep the task read-only, and stop before external effects.
• Write-capable work runs in a clean isolated branch, worktree, or scratch workspace. The parent reviews the diff before integration.

Canonical invocation

Run from the target repository:

cd <target-repo> && node "$COMPANION" task "<prompt>"

Supported routing flags include --background, --write, --resume-last, --fresh, --model <model>, and --effort <level>. Pass the prompt as one quoted argument. Leave model and effort unset unless the task or routing contract specifies them.

No --write means read-only. Add it only when the active workspace contract authorizes edits. Use one task call per delegated handoff; do not mix companion setup, review, status, or cancellation commands into that handoff.

Resume and background work

• --resume-last selects the latest resumable thread for the companion session, falling back to the target workspace only when no session id exists. Run it from the intended slice workspace.
• --fresh starts a new thread and requires the full prompt.
• Any task authorized to reach a browser or external/provider state runs with --background; capture its job id and Codex thread id before the task can mutate. Foreground execution is for bounded local or read-only work only.
• Background workers outlive the launching shell. Make the task write a report or committed handoff, and observe that deliverable plus worker liveness.
• A later shell process may not share the launcher's in-memory job registry. A "No job found" status response is not proof that the worker failed.
• Recover prose from the matching Codex rollout only after binding it to the recorded thread id. Never print stored request bodies because they may contain sensitive prompt content.
• If a worker is dead and exact thread binding is unavailable or ambiguous, start a fresh task from the intended workspace with full context.

Quiescence gate

Launcher exit is not worker exit. An interrupt, rate limit, empty event stream, nonzero exit, or missing report never proves that companion browser/tool sessions stopped or that external state is unchanged.

Before fallback, retry, or a zero-side-effect claim:

1. Cancel the exact background job and verify its worker is terminal; terminate any identified descendant tool worker that survived cancellation.
2. Release or finalize every browser tab/session owned by the recorded Codex thread. If ownership cannot be released, treat completion as ambiguous and stop.
3. Re-read the authoritative repository/provider state against the pre-dispatch baseline whenever the task had mutation authority. Logs and missing reports are not proof.

Done means all three checks pass. A user stop request runs this gate before any new task work.

Forwarding rules

• Preserve the user's task text apart from explicit runtime flags.
• Read-only review, diagnosis, research, and questions omit --write.
• Implementation uses --write only when authorized and isolated.
• Return the companion's stdout unchanged to the calling workflow; review artifacts and diffs separately before integration.
• Do not infer runtime identity from the agent's self-report. Use launcher/runtime metadata when vendor or model matters.

Native plugin entry points

When the installed Claude plugin exposes native commands, prefer its documented review, adversarial-review, rescue, and status surfaces. Use this contract for direct companion calls and for runtimes that need an explicit portable invocation shape.

Traps

• Run the helper with the shell working directory set to the target repository.
• A stale long-running Codex app server can retain an older binary after an upgrade. Verify the installed CLI and restart only the stale broker processes before retrying the same task.
• Long prompts must remain one argv; build them with a single-quoted heredoc.
• Never hand-edit companion job state. Reconcile liveness and rollout evidence, then resume exactly or start fresh.