Menu
Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | codex |
| description | Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing |
Before running any codex exec command, verify login status:
codex login status 2>&1
If not logged in, recover using one of:
# Option 1 โ API key, headless (preferred for automation)
# Source OPENAI_API_KEY from your own secret manager; never inline the literal key,
# and never echo it into a shell the user can see.
printenv OPENAI_API_KEY | codex login --with-api-key
# Option 2 โ Device auth (opens a browser)
codex login --device-auth
# Option 3 โ Interactive ChatGPT login (requires a real terminal)
# Tell the user to run it themselves: ! codex login
If login fails mid-run (non-zero exit plus an auth error in the output), run the recovery above once, then retry. Do not loop โ if it fails twice, stop and ask the user.
Note on model availability: ChatGPT sign-in and API-key sign-in do not expose the same model list, and the deprecations in Models below are specifically scoped to ChatGPT sign-in. If a model slug is rejected, check which auth mode is active before assuming the model is gone.
Current as of 2026-08-02. Codex ships model families faster than this file gets
updated, so treat the table as a floor, not a ceiling. The failure mode to avoid is
falling back to pre-GPT-5.6 names (gpt-5.4, gpt-5.3-codex, gpt-5.2) just because
they are the ones you remember from training โ those are deprecated or already retiring.
If the installed CLI offers something newer than what is listed here, prefer the newer
thing and update this table.
| Slug | Tier | Reach for it when |
|---|---|---|
gpt-5.6-sol | Deep-reasoning flagship | Ambiguous, high-value, architecturally hard work โ complex refactors, deep debugging, design review |
gpt-5.6-terra | Everyday workhorse | Default for most dispatches. Roughly GPT-5.5-class at about half the price |
gpt-5.6-luna | Fast / cheap | High-volume, latency-sensitive, mechanical work โ bulk edits, subagents |
| Slug | Status |
|---|---|
gpt-5.5 | Previous frontier default (since 2026-04-23). Superseded by gpt-5.6-terra/-sol for most work |
codex-auto-review | Purpose-built reviewer/guardian model, visibility: hide in the catalog. Not a general driver โ do not dispatch ordinary tasks to it |
gpt-5.3-codex-spark (sub-second latency, 128K text-only) is absent from the current
models_cache.json and must not be offered as a choice. Historical note only.
| Slug | What happened | Replace with |
|---|---|---|
gpt-5.4 | Retires from Codex with ChatGPT sign-in on 2026-08-31 | gpt-5.6-terra |
gpt-5.4-mini | Retires from Codex with ChatGPT sign-in on 2026-08-31 | gpt-5.6-luna |
gpt-5.3-codex | Deprecated for ChatGPT sign-in | gpt-5.6-terra |
gpt-5.2 | Deprecated for ChatGPT sign-in | gpt-5.6-sol |
โ ๏ธ The 2026-08-31 retirement is imminent. If ~/.codex/config.toml, a custom agent,
or a scheduled task still names gpt-5.4 or gpt-5.4-mini, say so and offer to migrate
it before dispatching.
Passed as --config model_reasoning_effort="<effort>". Effort support and the default
are per-model, not global. Verified against ~/.codex/models_cache.json on 2026-08-03:
| Model | Default | Supported efforts |
|---|---|---|
gpt-5.6-sol | low | low, medium, high, xhigh, max, ultra |
gpt-5.6-terra | medium | low, medium, high, xhigh, max, ultra |
gpt-5.6-luna | medium | low, medium, high, xhigh, max |
codex-auto-review | medium | low, medium, high, xhigh, max |
gpt-5.5 | medium | low, medium, high, xhigh |
gpt-5.4 | medium | low, medium, high, xhigh |
gpt-5.4-mini | medium | low, medium, high, xhigh |
gpt-5.6-sol defaults to low. Dispatching the deep-reasoning flagship without an
explicit effort gets you its weakest setting โ and --ignore-user-config drops the
config default too, so the trap fires precisely in headless dispatches. Always pass
effort explicitly with sol.
ultra is a real effort value, on sol and terra only โ maximum reasoning with
automatic delegation to parallel subagents. It is not a separate feature reached some
other way. max is real on every GPT-5.6 model and on codex-auto-review; the pre-5.6
models cap at xhigh.
minimal and none are recognized by the CLI's own enum but are advertised by no
cached model, so a request for either is normalized or dropped rather than honoured.
The per-model list above is authoritative over the CLI's accepted-value set.
An unsupported value is coerced rather than rejected โ a dispatch behaving like low
when you asked for more may mean the value never took, not that the model underperformed.
Do not guess from memory โ it goes stale in weeks. Check, in order:
~/.codex/config.toml โ the model = line is the user's chosen default.~/.codex/models_cache.json โ what this install last saw the API offer./model picker in an interactive codex session.Prefer the user's configured default, but if it names a retired model, flag it instead
of silently using it. Ask for model + reasoning effort together in one AskUserQuestion
when the user has not specified them.
Check login (Pre-flight above).
Ask model + reasoning effort in one AskUserQuestion if not given. Offer current slugs from Models (gpt-5.6-terra default) โ never a pre-5.6 name.
Sandbox: read-only unless the task genuinely writes. Note what read-only does and
does not mean โ it constrains writes, not command execution. A read-only dispatch
still runs arbitrary shell (/bin/zsh -lc ...), so it can read any file the user can
read and reach the network. It is a write guard, not a containment boundary. Never pick
danger-full-access merely because a task wants network.
Assemble the command. -a never is TOP-LEVEL, not exec-level โ it goes BEFORE exec:
codex -a never exec [options] "prompt"
codex exec -a never ... errors with unexpected argument '-a' found.
| Flag | |
|---|---|
-a never | approval policy โ before exec |
-m, --model <MODEL> | |
--config model_reasoning_effort="<effort>" | |
--sandbox <read-only|workspace-write|danger-full-access> | |
-C, --cd <DIR> | run from another directory |
--skip-git-repo-check | only when the target really is outside a git repo |
"prompt" | final positional argument |
NEVER pass --full-auto. It silently escalates your sandbox. It is a real, hidden,
deprecated exec-level flag โ not the no-op earlier versions of this skill claimed. It
forces workspace-write and approval never, overriding an explicit
--sandbox read-only that appears later on the same command line.
Verified on Codex 0.146.0, 2026-08-03:
| Command | approval | sandbox |
|---|---|---|
codex exec --sandbox read-only | on-request | read-only |
codex exec --full-auto --sandbox read-only | never | workspace-write [workdir, /tmp, $TMPDIR] |
The only signal is warning: --full-auto is deprecated on stderr โ which the
2>/dev/null in older examples would discard. Believing the flag is inert while
discarding the one message that says otherwise is how an agent ends up with write
access to the workdir and /tmp while thinking it has read-only. Non-interactive means
-a never plus an explicit --sandbox <mode>, and nothing else.
--skip-git-repo-check is not a default either. It disables the guard that makes
Codex refuse an untrusted directory, so a malformed -C proceeds in $HOME or a parent
directory instead of failing closed. Inside a repo, omit it. Outside one, verify the
absolute path first, and ask before pairing it with a writable sandbox.
-a never on every non-interactive dispatch. Without it codex blocks on a TTY-only "do you trust this folder?" prompt the first time it runs in a directory โ invisible and unanswerable behind 2>/dev/null | tail -N. It does not bypass sandboxing (that is --dangerously-bypass-approvals-and-sandbox, unused here); a would-be approval returns to the model as a failure instead.
--ignore-user-config by default for headless code-fix dispatches (exec-level). Skips ~/.codex/config.toml, so no MCP servers initialize โ see hang mode 2, which -a never does not cover. Auth still works via CODEX_HOME. It also drops the config's model + effort, so pass both explicitly. Keep the flag off only when a task genuinely needs an MCP server.
Do not blanket-discard stderr. 2>/dev/null hides thinking tokens, but it also
hides deprecation warnings, auth failures, the resolved sandbox, and which model was
actually selected โ the exact evidence Error Handling below tells you to inspect.
Redirect to a file instead and read it on any non-zero exit or surprising result:
2>/tmp/codex-<task>.err. Keep 2>/dev/null only for runs whose stderr you have
already decided you will never need.
Run, summarize, then tell the user they can resume any time by saying "codex resume".
Base invocation โ note it carries --ignore-user-config and an explicit effort, as
steps 6 and 7 require, and sends stderr to a file rather than discarding it:
codex -a never exec --ignore-user-config \
-m gpt-5.6-terra --config model_reasoning_effort="high" \
--sandbox read-only "prompt" 2>/tmp/codex-review.err
| Use case | Change from the base |
|---|---|
| Read-only review | base as written |
| Apply local edits | --sandbox workspace-write |
| Run from another dir | add -C <ABSOLUTE_DIR> |
| Target is outside a git repo | add --skip-git-repo-check, after verifying the absolute path |
| Resume a session | resume <SESSION_ID> with the prompt on stdin โ see Following Up |
| Network access | Do not reach for --sandbox danger-full-access. It grants unrestricted filesystem and network to model-generated commands. Needing to fetch a doc is not a reason to disable the sandbox โ narrow the task, fetch the content yourself and pass it in, or tell the user this environment cannot grant network safely. |
AskUserQuestion after every dispatch โ next steps, or whether to resume.--last. It resolves to whichever Codex session finished most
recently, machine-wide. Another agent's dispatch completing in between silently hijacks
your resume, and under a writable sandbox that edits the wrong project. Capture the
session id from the dispatch banner (session id: <uuid>, or use --json) and resume
that id explicitly.-m, the effort, and
--sandbox explicitly whenever continuity matters.Codex has its own knowledge cutoff and failure modes. Colleague, not authority.
When Codex is wrong: state the disagreement, give evidence, optionally resume peer-to-peer identifying yourself as Claude, and let the user decide genuine ambiguity.
echo "This is Claude (<model>) following up. I disagree with [X] because [evidence]. Your take?" \
| codex -a never exec --skip-git-repo-check resume --last 2>/dev/null
For anything expensive to get wrong, do not freehand it โ use /clodex: two reviewers aimed at different failure classes, every claim verified before it is relayed, and the fixes split under a contract negotiated rather than assigned.
For projects carrying docs/arch/STATE.json + docs/arch/contracts/.
Lifecycle: pending โ specced โ codex-dispatched โ review โ done
Read STATE.json, find the next specced candidate.
Read its contract file.
Pipe the contract in as the prompt:
contract=$(cd "<project-dir>" && pwd)/docs/arch/contracts/<n>-<name>.md
codex -a never exec --ignore-user-config -m <model> \
--config model_reasoning_effort="high" \
--sandbox workspace-write -C "<project-dir>" - \
< "$contract" 2>/tmp/codex-contract.err
Pass the contract on stdin, with an absolute path. The obvious
"$(cat docs/arch/contracts/...)" form is broken twice over: the shell expands $(cat โฆ)
in your cwd before Codex ever applies -C, so it reads the wrong project's contract or
fails outright, and a large contract can blow the argv limit. Despite the surrounding
prose calling it a pipe, that form is not one.
Set status: "codex-dispatched" and codex_session: "last".
On completion โ status: "review"; verify against the contract's Success criteria.
After human sign-off โ status: "done".
Every contract file needs all of: Goal, Seam (types, methods, invariants), Files to touch, Files NOT to touch, Tests required, Success criteria (checkable), Out of scope, and โ critically โ do not remove existing tests: add only. Codex rewrites test files and silently drops existing cases unless told otherwise. Do not dispatch until every section is filled.
Stop and report on any non-zero exit; ask before retrying. Auth errors โ pre-flight recovery, retry once. Ask via AskUserQuestion before --sandbox danger-full-access or --skip-git-repo-check unless already granted. Summarize warnings and partial results, then ask how to adjust.
0% CPU, blocked on invisible TTY input, first run in a new directory. Re-dispatch with
-a never. Confirmed 2026-05-13: 27 min at 0% CPU before the kill.
Kill by recorded PID, never by pattern. pgrep -f "codex exec" does not kill anything
on its own, and its pattern is not session-specific: it matches every concurrent Codex on
the machine โ including other agents' workspace-write dispatches, which a pattern-kill
would interrupt mid-edit. It also matches your own wrapper shell if that shell's command
line happens to contain the string, which turns an until ! pgrep โฆ wait into an infinite
loop. Capture $! when you launch and kill only that PID.
-a never)codex exec initializes every MCP server declared in ~/.codex/config.toml before doing any work; one that fails to come up blocks forever.
rollout-*.jsonl and a growing stderr file. Killing on CPU alone will
routinely kill working dispatches.~/.codex/sessions/<YYYY>/<MM>/<DD>/ โ a working run writes rollout-*.jsonl almost immediately. Nothing recorded means it never got past startup, not that it is running slowly. Confirm servers are configured: grep -c '\[mcp' ~/.codex/config.toml.--ignore-user-config. Skips config.toml entirely; auth still works via CODEX_HOME. Pass -m and --config model_reasoning_effort explicitly, since the config's defaults go with it.-a never set, recording zero session files; a probe with --ignore-user-config exited 0 in under 100s.A --sandbox workspace-write dispatch can exit 0 and fire the caller's task notification while still flushing files for a few seconds. New changes can appear after you already reviewed, tested, and committed.
Compare content hashes, not git status text. Two git status runs are not a
stability check. A file already listed as M src/auth.ts that a late writer changes
again is still M src/auth.ts โ identical status output, different bytes. Verified
2026-08-03: same porcelain output across a modification, different shasum.
Do this instead:
wait "$codex_pid" # exited process cannot flush more writes
snap() { git status --porcelain | awk '{print $2}' | xargs shasum 2>/dev/null; }
a=$(snap); sleep 5; b=$(snap)
[ "$a" = "$b" ] && echo "tree stable"
Waiting for the dispatch process and its descendants to exit is the real guarantee; the hash re-check is the backstop for anything it spawned and orphaned.
Never discard late changes just because they look redundant. Resemblance is not provenance: those bytes may be the user's own edit, or another agent's, arriving in a shared checkout. Establish where they came from, keep a patch or backup, and get approval before discarding anything.