Agent Skills: Codex CLI

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:

| Plugin skill | Use for | |--------------|---------| | codex:setup | Check Codex is installed, configured, and ready | | codex:rescue | Delegate a rescue/fix/diagnosis/research task to Codex | | codex:codex-result-handling | Internal — how to present Codex output back to the user | | codex:gpt-5-4-prompting | Internal — prompt drafting for Codex |

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:

| Doctor line | What to do | |------|---------| | model <name> · openai (under Configuration) | This is the current default — use it as-is; don't override unless the user names a specific model | | ↑ updates X.Y.Z available (current A.B.C) | Surface to the user: "Codex 0.133.0 is available, you're on 0.132.0 — run codex update when convenient." Do NOT auto-update (slow + can break in-flight sessions). | | auth auth is configured | Good. If not configured, tell user to codex login first. | | network … not reachable | Network/proxy issue — surface to user, don't blind-retry. |

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):

| Level | When to override the default to this | |-------|---------------------------------------| | none | Pure pass-through, no reasoning | | minimal | Trivial transformations. May 400 on some models — fall back to low if it errors | | low | Simple Q&A, short generations, format conversions. ~half the tokens of medium | | medium | Code review of a file, second-opinion audit, one-shot refactor | | high | Repeated/failing tasks needing deeper analysis, complex multi-step planning, explicit user request | | xhigh | Last-resort heavy reasoning. Only when high has failed |

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:

| Mode | Behavior | |------|----------| | read-only | Agent can read but not write. Use for audits, second opinions, diagnostics. | | workspace-write | Agent can write inside the workspace (and --add-dir paths). Use for refactors/implementations you expect to land. | | danger-full-access | No filesystem restrictions. Only with explicit user OK + trusted prompt. |

-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:

| Flag | What it actually skips | |------|------------------------| | --dangerously-bypass-approvals-and-sandbox | Bypasses both approval prompts and sandbox. Intended only for externally-sandboxed environments (containers, VMs). | | --dangerously-bypass-hook-trust | Runs configured hooks without requiring persisted trust. Use only in automation that already vets hook sources. | | --full-auto | Deprecated. Codex itself now tells you: "use --sandbox workspace-write instead". |

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

| Subcommand | Use for | |-----------|---------| | codex exec [PROMPT] | Headless one-shot | | codex exec resume [ID\|--last] [PROMPT] | Continue a prior session non-interactively | | codex review {--uncommitted\|--base BRANCH\|--commit SHA} | Review a diff in the repo | | codex resume [ID\|--last] | Resume an interactive session (picker if no ID) | | codex fork [ID] | Fork a prior session into a new branch | | codex archive <id> / unarchive | Archive sessions (archived = protected from resume/fork) | | codex apply <TASK_ID> | git apply the latest diff Codex produced for <TASK_ID> | | codex doctor | Diagnose install, auth, config, connectivity, sandbox — first stop when anything's broken | | codex mcp {list,get,add,remove,login,logout} | Manage MCP servers Codex calls into | | codex sandbox [CMD] | Run an arbitrary command inside Codex's sandbox | | codex features {list,enable,disable} | Toggle feature flags (hooks, multi_agent, image_generation, etc.) | | codex update | Upgrade Codex to latest | | codex login / codex logout | Auth management |

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

| Flag | Description | |------|-------------| | -c 'key="value"' | Override any config (works everywhere; preferred over -m for review) | | -m | Model shorthand (works with exec, not with review) | | -s | Sandbox: read-only / workspace-write / danger-full-access | | -a | Approval policy (top-level, before subcommand): untrusted / on-request / never | | -C | Working directory root | | --add-dir <DIR> | Additional writable directories beyond workspace | | -o, --output-last-message <FILE> | Write final assistant message to a file | | --json | Stream events as JSONL on stdout — for piping into other tools | | --output-schema <FILE> | Path to JSON Schema describing the final response shape (structured output) | | --ephemeral | Don't persist a session file to disk (one-shot, no resume) | | --ignore-user-config | Don't load ~/.codex/config.toml — for reproducible CI behavior | | --ignore-rules | Don't load .rules files | | --skip-git-repo-check | Allow running outside a Git repo | | --search | Enable native web_search tool (top-level flag) | | -i, --image <FILE> | Attach images to the initial prompt (multimodal) | | --oss --local-provider {ollama,lmstudio} | Use a local OSS model instead of OpenAI | | --no-alt-screen | Inline TUI mode (preserves scrollback) |

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.