Codex

Verify installed

Run codex exec --help once per session — it confirms install and is the authoritative current CLI/parameter reference (the CLI evolves; docs lag). If codex: command not found, send the user to https://openai.com/codex/ and stop.

Liveness probe (run before a panel or long job — it pins the model, so access failures like a too-old CLI surface now instead of mid-run; low effort because it's a ping, not a panel call):

codex exec --skip-git-repo-check -c model="gpt-5.6-sol" -c model_reasoning_effort="low" -o ~/claude/scratch/codex_probe.txt - <<<"Reply with exactly: CODEX-OK" 2>&1 | tail -1

Preferences

Pass these explicitly on every call so the skill works regardless of the user's ~/.codex/config.toml:

• model: gpt-5.6-sol — this skill owns the codex model name; a unit test (test_model_names.py) keeps every mention in this file identical, so bump them all together
• Codex serves the sol / terra / luna model family: sol is the flagship and the pin above; luna is the small cheap fast tier — remarkably cost-effective, very smart for its price, the pick for high-volume work; terra sits between. When the user names terra or luna explicitly, run that tier — same flags, with the tier's name swapped into the model id (both verified live 2026-07-17); the default stays sol
• reasoning effort: xhigh
• service tier: fast

Flag form: --sandbox read-only -c 'web_search="live"' -c model="gpt-5.6-sol" -c model_reasoning_effort="xhigh" -c service_tier="fast". Everything rides in the flags — the user's ~/.codex/config.toml may pin its own defaults, but invocations never depend on it and install never writes it.

Always background

Codex runs for anywhere from about a minute to half an hour (occasionally longer). Set run_in_background: true on Bash. You'll be notified on exit; use BashOutput for mid-run peeks. -o writes Codex's final message only, at completion.

Send a prompt from a file

ts=$(date +%Y%m%d_%H%M%S)_$$
prompt=~/claude/scratch/prompt_codex_${ts}.md
out=~/claude/scratch/output_codex_${ts}.txt
# Write your prompt into $prompt (Write tool), then:
codex exec --sandbox read-only --skip-git-repo-check \
  -c 'web_search="live"' \
  -c model="gpt-5.6-sol" \
  -c model_reasoning_effort="xhigh" \
  -c service_tier="fast" \
  -o "$out" - < "$prompt"

Codex has read tools + web search — point it at files, don't inline source.

--skip-git-repo-check is not optional here. Codex refuses to start outside a git repo, and the scratch dir this pattern writes to is not one — so a call made from ~/claude/scratch dies before reaching the model. It costs nothing when the cwd is a repo, so keep it on every advisory call rather than making it conditional on where you happen to be.

Read-only by default

Advisory calls (reviews, second opinions, research) run --sandbox read-only: Codex reads any file and searches the web, but model-run commands can't write — a reviewer that starts "fixing" the code under review clobbers the caller's working tree. Read-only costs nothing: the -o output file is written by the CLI itself after the run, not by the model, so the default flow above needs no write access. Web search is a hosted tool the local sandbox doesn't gate; --search is TUI-only, so in exec pin it via config: -c 'web_search="live"' (default "cached" serves OpenAI's crawl cache). Verified on 0.144.5: writes blocked with "operation not permitted", live search works, -o still written.

Delegating work that must write (edit files, produce artifacts): swap in --sandbox workspace-write — writes allowed in the cwd (pass -C <dir> to aim it) plus any --add-dir directories; shell network stays off unless you add -c sandbox_workspace_write.network_access=true. Say so explicitly in the prompt, and point it at a worktree or scratch dir, never a tree another agent is editing.

Strengths and weaknesses

Hard math, novel algorithms, multi-file tracing, tool-grounded technical judgment, deep correctness work, web-grounded research.

Watch for overthinking at xhigh. Frame "are there real problems?" not "find problems."

Troubleshooting

• Not inside a trusted directory and --skip-git-repo-check was not specified — the cwd is not a git repo. Add --skip-git-repo-check (already in the patterns above). Note this fails before the model runs, so -o never gets written and the output file is simply absent — don't read the empty file as an empty answer.
• ERROR: You've hit your usage limit — the ChatGPT subscription has a rolling Codex budget; the error includes a retry time. Fall back to gemini/claude or wait.
• model "gpt-5.6-sol" does not exist or you do not have access — ChatGPT tier missing Codex (needs Plus/Pro/Business/Enterprise/Edu).
• The 'gpt-5.6-sol' model requires a newer version of Codex — this model family needs Codex CLI ≥ 0.144.0 (verified 2026-07-09). Don't self-update mid-task; tell the user to upgrade codex, and fall back to the prior model — naming the substitution — until they do.
• Reasoning effort silently lowered after a model upgrade — Codex resets reasoning to the new model's default on accepted upgrades. The explicit -c flags above immunize against this.