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'.)
• --commit <SHA> and [PROMPT] are mutually exclusive — cannot combine.
• --base <BRANCH> and [PROMPT] can be combined.
• --uncommitted and [PROMPT] can be combined.
• WRONG: codex review --commit abc123 "Review for security"
• Correct: codex review --commit abc123
• Correct: codex review --base main "Focus on security"

Workaround for --commit with custom instructions

git diff <SHA>~1..<SHA> | codex exec -s read-only -

Subcommands worth knowing

Useful flags reference (most useful in headless / Claude-driven runs)

Top-level vs. subcommand flag placement

--search and -a/--ask-for-approval are top-level flags. Put them before exec or review.

Correct:

codex --search -a on-request exec "Your prompt"
codex -a never exec "Your prompt"

WRONG:

codex exec --search "Your prompt"
codex exec -a on-request "Your prompt"

Efficient execution from Claude (don't idle-wait)

Long codex exec runs (especially with high/xhigh effort or autonomous refactors) can take minutes. Always invoke with `run_in_background: true` so the harness wakes Claude on actual exit — don't poll the output file in a sleep loop.

# RIGHT — Claude is notified the moment codex exits, whether 30s or 30m
Bash(command="codex exec -s read-only -c 'model=\"gpt-5.5\"' \"audit...\" -o /tmp/codex.out",
     run_in_background=true)
# → wait for completion notification, then Read /tmp/codex.out

# WRONG — burns wall clock and prompt cache
Bash(command="codex exec ...")          # foreground blocks Claude
sleep 300 && cat /tmp/codex.out         # polling = idle waste

For very long runs also pass --json to a log file and tail-inspect progress without re-invoking:

codex exec --json -c 'model_reasoning_effort="high"' "..." 2> /tmp/codex.events.jsonl

Rate limits and abuse heuristics

Codex shares quota across all your invocations on the same auth (whether ChatGPT subscription or API key). Bot-like patterns trigger throttling and, on repeated 429s, account-level slow-downs.

• Never run two `codex exec` processes in parallel. Serialize. If Claude has three things to ask, send three sequential prompts or combine into one.
• Reuse sessions with codex exec resume --last instead of cold-starting every time.
• On 429 / `rate limit` / `quota exceeded` in output: stop and report, do not retry. No while ! codex …; do …; done loops.
• Don't loop on failure. Fix the prompt before re-running; if medium failed, try high once, not five times.
• Be explicit about output length ("answer in ≤5 bullets", "code only, no commentary") — every turn costs tokens.
• Pair `--ephemeral` with one-off scripted calls so you don't accumulate junk sessions in ~/.codex/.
• Use `--oss` when developing/debugging Codex CLI usage itself so you don't burn paid quota on plumbing tests.

Comparison workflow with Claude

When the user wants a second opinion:

1. State Claude's answer/recommendation first.
2. Run the same question via codex exec -s read-only "<same prompt>".
3. Present both side-by-side. Highlight where they agree/disagree.

Pick a higher sandbox (or use codex review) only if the user wants both agents to implement, not just opine.

Recommended invocation patterns

All examples use Codex's default model + effort. Only add -m/-c 'model_reasoning_effort=...' if the user explicitly asks.

# Second-opinion audit (read-only)
codex exec -s read-only --ephemeral \
  "Audit src/auth/ for OWASP issues. Report only — do not modify files."

# Headless build / refactor (writes to workspace)
codex exec -s workspace-write -C "$(pwd)" --add-dir ./packages/api \
  -o /tmp/codex.out \
  "Implement the /healthz endpoint with a unit test."

# Review uncommitted changes
codex review --uncommitted "Focus on security and error-handling."

# Review against base branch
codex review --base main "Check for performance regressions."

# Review a specific commit (NO custom prompt allowed with --commit)
codex review --commit abc1234

# Pipe a specific diff for review with custom instructions
git diff HEAD~1..HEAD | codex exec -s read-only --ephemeral -

# Structured output (JSON Schema)
codex exec --output-schema /tmp/schema.json \
  "Extract all TODO comments as {file, line, text} objects."

# Resume the last session with follow-up
codex exec resume --last "Now add error handling to that route."

# User explicitly wants high reasoning effort
codex exec -c 'model_reasoning_effort="high"' "Diagnose why this race appears 1-in-50 runs"

# User explicitly names a model
codex exec -m gpt-5.4 "Compare gpt-5.4 vs current default on this prompt"

# Local OSS model (no remote quota)
codex exec --oss --local-provider ollama -m llama3.1 "Quick sanity check on this regex"

Best practices (quick checklist)

• Preflight once per session with codex doctor — note the current default model, surface any available update to the user, never auto-update.
• Leave model + effort unset by default. Codex picks the current best default; hardcoding makes invocations go stale. Add -m / -c 'model="…"' / -c 'model_reasoning_effort="…"' only when the user explicitly asks.
• Prefer `codex:rescue` plugin for "delegate to Codex" requests when the plugin is installed. Use direct codex exec for explicit CLI tasks the user typed.
• Default sandbox: `read-only`. Escalate to workspace-write only when you expect file changes; danger-full-access requires explicit user OK.
• Always `run_in_background: true` and let the harness fire the completion notification — no polling.
• For commit reviews with custom instructions, pipe git diff to codex exec - (since --commit and [PROMPT] are mutually exclusive).
• Add -o <file> when another tool or agent must consume the result.
• Use --ephemeral for one-shot scripted calls so you don't accumulate junk sessions in ~/.codex/.
• Use --ignore-user-config in CI for reproducibility independent of ~/.codex/config.toml.
• Serialize codex calls — never two in parallel. On 429: stop, report, don't retry.
• Pair --dangerously-bypass-approvals-and-sandbox only with an externally-sandboxed environment (container, VM). Never on a bare developer machine.
• Run codex doctor first whenever anything misbehaves — it surfaces auth, config, sandbox, and connectivity issues in one pass.
• --full-auto is deprecated; use --sandbox workspace-write instead.