Codex

codex — independent Codex review (plan + code)

A universal, on-demand wrapper around the codex CLI that gives you an independent second opinion on your work. It is project-agnostic — it works in any directory, git repo or not — and not tied to any particular workflow. Invoke it directly when the user asks for a Codex review, or programmatically from another skill (e.g. gsd runs it at its plan and code checkpoints).

Codex is advisory, never blocking. Every call is best-effort: if the codex CLI is missing, out of quota, or times out, the script prints a note and exits 0 — you report "Codex review skipped" and continue. Codex never gates completion. Treat its output as a strong outside opinion: adopt what's valid, briefly note what you reject with a reason, move on.

The driver is the codex.sh bundled with this skill — installed as a plugin it lives at ${CLAUDE_PLUGIN_ROOT}/codex.sh; copied as a plain skill folder, at <skill-dir>/codex.sh. It has two modes, plan and code. The examples below write codex.sh for brevity — substitute the bundled path. <root> = the project directory Codex is allowed to read.

Requirements: the codex CLI on PATH and available quota. The driver uses the Codex-specific model ID gpt-5.6-sol by default. Do not shorten this to gpt-5.6: that is a different, unsupported model ID for ChatGPT-account Codex auth. Override deliberately with CODEX_REVIEW_MODEL=<model-id> when needed. The review is read-only and can take several minutes; the diff handed to Codex is capped at ~120k chars, but Codex has read access to the whole project and is told it may open full files.

---

Mode 1 — Plan review (before code is written)

Have Codex critique a design/plan document for weak points before implementation. Verdict: VERDICT: SOLID or VERDICT: WEAKNESSES + a numbered list.

# Explicit plan file(s):
codex.sh plan <root> path/to/PLAN.md [more-plan-files...]

# Or, with no files given, auto-discover GSD plan artifacts under <root>/.gsd/
# (RESEARCH.md, REQUIREMENTS.md, ROADMAP.md, FORKS.md, S*-PLAN.md):
codex.sh plan <root>

Codex looks for: missing tasks/requirements, wrong or circular dependencies, tasks too coarse to verify, vague acceptance criteria, risky assumptions, scope gaps, reuse the plan ignored, and parallelization hazards.

Act on the verdict: SOLID → note it and proceed. WEAKNESSES → for each point decide if it's a real gap; apply the valid ones to the plan, and briefly record anything you deliberately reject with a reason. You may re-run once to confirm; don't loop — stop after at most two rounds and log any residual. The goal is a stronger plan, not a perfect one.

---

Mode 2 — Code review (after a round of changes)

Have Codex review a diff against the instruction it was meant to satisfy. Verdict: VERDICT: APPROVE or VERDICT: COMMENTS + a numbered list.

1. Assemble the changed-file list (newline-separated absolute paths). Any accurate source works:

   # From git — changed tracked files AND new untracked ones, as absolute paths
   # (plain `git diff --name-only` alone would miss newly-created files):
   { git -C <root> diff --name-only; git -C <root> ls-files --others --exclude-standard; } \
     | sed "s#^#<root>/#" | sort -u > /tmp/codex-files.txt
   # For an already-committed range (e.g. a whole feature branch — pair with CODEX_DIFF_BASE below):
   #   git -C <root> diff --name-only <base>..HEAD | sed "s#^#<root>/#" > /tmp/codex-files.txt
   # …or an explicit list of the files you changed, one per line.
   

2. Write the instruction the diff must satisfy (the user's request, a slice goal, the success criteria — the verdict is judged against it):

   printf '%s\n' "<the instruction / goal for this round>" > /tmp/codex-instr.md
   

3. Run the review:

   codex.sh code <root> /tmp/codex-instr.md /tmp/codex-files.txt
   

   • Non-git projects work out of the box (new files are diffed against /dev/null).
   • To review already-committed changes (e.g. a whole feature branch vs its base, where git diff HEAD is empty), set the base ref:

     CODEX_DIFF_BASE=<base-commit-or-branch> \
       codex.sh code <root> /tmp/codex-instr.md /tmp/codex-files.txt
     

4. Act on the verdict: APPROVE → done. COMMENTS → treat each numbered item: fix what's valid, note anything you disagree with and why, then optionally re-run. Codex reviews only code/doc content, not repo hygiene or version-control practices.

---

Notes

• To verify model access, run a tiny codex exec --model gpt-5.6-sol probe and check both the startup banner's model: line and a successful response. CLI argument acceptance alone does not prove backend access.
• Out-of-quota / timeout / exec errors print to stderr and yield no verdict — the same non-blocking behavior in both modes. Report "review skipped" and continue.
• For diff-based code review in a git repo, prefer running git init early on greenfield projects so tracked-file diffs are available; non-git still works via --no-index.