Codex CLI

OpenAI's local agentic coding CLI (codex, v0.132+). Runs the GPT-5 family by default (current default: gpt-5.5) and supports OSS providers (ollama, lmstudio). Use for second-opinion audits, delegated builds, review of uncommitted diffs, and non-interactive task execution.

First: prefer the Codex Claude Code plugin when it's installed

If the user has the official openai-codex plugin in ~/.claude/plugins/marketplaces/openai-codex/, the plugin's skills are the preferred path for Claude→Codex delegation:

The plugin wraps codex with a task runner that handles background execution, model/effort routing, write-vs-read, and result fetching. Hand-rolling codex exec from Bash is fine for direct CLI work (e.g. the user explicitly types codex … or wants a one-off review), but for "delegate this to Codex" requests, prefer codex:rescue. Don't double-invoke.

Detect with: ls ~/.claude/plugins/marketplaces/openai-codex/ 2>/dev/null

Prerequisites

codex --version                       # Confirm install
codex doctor                          # Diagnose install + auth + config + connectivity
codex login                           # First-time auth (ChatGPT subscription OR API key)
codex update                          # In-place update (DON'T run automatically — surface to user)

Auth modes (codex doctor shows which is active):

• ChatGPT subscription (stored_auth_mode: chatgpt) — default; uses your ChatGPT plan quota
• API key (stored_auth_mode: apikey) — billed per token via OpenAI API
• OSS (--oss --local-provider {ollama,lmstudio}) — local model, no remote quota

Preflight: check version + current default before invoking

Before the first codex exec/codex review in a session, run a quick preflight. Do NOT repeat for every call — once per session is enough.

codex doctor 2>&1 | grep -E "(version|model|auth|updates)" | head -20

What to look for:

Skip the preflight (and just invoke) if the user explicitly asks for speed or for a one-off trivial query.

Core execution pattern

codex exec "Your prompt here"                            # one-shot, default model + effort
echo "context..." | codex exec -                         # read prompt from stdin
codex exec resume --last "Now add tests"                 # resume most recent session
codex exec resume <SESSION_UUID> "Continue"              # resume specific session

When the user says "codex prompt", treat it as codex exec "<user prompt>". Pick effort and sandbox based on task shape (see below).

Model + reasoning effort — leave unset by default

Don't hardcode a model or effort in invocations. Codex tracks the current best default in ~/.codex/config.toml and ships new defaults with each release. Hardcoding -c 'model="..."' or -c 'model_reasoning_effort="..."' makes calls go stale (this skill itself was pinned to a deprecated gpt-5.4 for months). Match the official plugin's rule:

Leave model unset by default. Add -m/-c model="…" only when the user explicitly asks for a specific model. Leave reasoning effort unset unless the user explicitly requests a level.

To see what the current default actually is: codex doctor reports it as model <name> · openai under the Configuration section. Don't bake that value into the invocation — it's just for your awareness.

Model names you may see in 2026 (snapshot, may shift): gpt-5.5 (current default), gpt-5.4, gpt-5.3-codex-spark (the "spark" alias in the plugin), o3. Set via -m <name> (works on exec, not on review) or -c 'model="<name>"' (works everywhere).

Reasoning effort levels (six, set via -c 'model_reasoning_effort="<level>"' — but normally leave unset):

Escalate only when a default-effort run failed or produced surface-level output. Don't default to high "to be safe" — it burns 5–10× the tokens.

# Default invocation — let Codex pick model + effort
codex exec "Audit this for race conditions"

# User explicitly asks for a cheap quick lookup
codex exec -c 'model_reasoning_effort="low"' "What does ETIMEDOUT mean in posix?"

# User explicitly asks for deep analysis
codex exec -c 'model_reasoning_effort="high"' "Diagnose why this test flakes 1-in-20 runs"

# User explicitly asks for a specific model
codex exec -m gpt-5.4 "Compare against gpt-5.4's answer"

Sandbox + approval policy

-s, --sandbox selects the filesystem policy:

-a, --ask-for-approval (top-level flag, before subcommand) selects when Codex asks before running shell commands: untrusted, on-request (default for interactive), never (default for non-interactive). on-failure is deprecated.

The three "dangerous" flags — know the difference:

Critical argument compatibility rules

These prevent CLI errors. Confirmed against v0.132.

codex exec

• [PROMPT] is the only positional arg. Passing both - (stdin) and a quoted prompt errors with unexpected argument '-' found — pick one.
• Correct stdin: cat file.txt | codex exec -s read-only -
• Correct prompt arg: codex exec -s read-only "your prompt"
• WRONG: cat file.txt | codex exec -s read-only - "your prompt" (two positional args)
• When the user names a specific model: codex exec -m <name> "…" (or -c 'model="<name>"').

codex review

• -m does not work on codex review — if the user names a model, use -c 'model="<name>"'. (If you literally need the string -m in a prompt, the error tip says use '-- -m'.)
• `-