Review and Refine Code with AI

Codex Review sets up a cross-agent review loop: Claude does the implementing, and a separate Codex (GPT) CLI session - running in the same directory, with its own view of the code - does the reviewing. The workflow covers two review points: the plan, before any code is written, and the resulting code, after implementation. Each round produces a verdict of APPROVED or CHANGES_REQUESTED, written by Codex to a verdict.txt file (or parsed from its response text as a fallback), and tracked through a STATUS.md file and a small state store scoped to the current git branch.

Use it whenever a task should get a second, independent opinion from a GPT-based reviewer before it's considered done - both at the planning stage (send the plan for review before calling ExitPlanMode) and again after implementation (send a description of what changed before finishing). Do NOT call codex exec directly under any circumstances - the skill's own rules require going only through codex-review.sh and codex-state.sh, which manage the model, config, and session ID correctly. Also do not run those scripts inside the default sandbox: Codex CLI depends on macOS system APIs (SCDynamicStore) that the Claude Code sandbox blocks, causing a Rust panic, so every call must set dangerouslyDisableSandbox: true.

A review session starts with bash scripts/codex-review.sh init "task description" (or by manually setting CODEX_SESSION_ID in .codex-review/config.env). Plan review takes a full plan description as its argument - Codex cannot see files outside the project folder - structured as What / Approach / Alternatives considered / Files to change / Addressed concerns, e.g. codex-review.sh plan "What: JWT authentication... Approach: ... Files: auth/jwt.py, api/auth.py". Code review similarly takes a description of what changed and why (never a raw git diff, since Codex can inspect the code itself), structured as What changed / Key decisions / Files modified / Tests / Addressed concerns. Exit codes map to actions: 0+APPROVED means continue, 0+CHANGES_REQUESTED means revise and resubmit, 1 is an error (check the session ID), 2 is ESCALATE (iteration limit hit), and 3 is NO_SESSION (no session configured yet). State can be inspected and managed with codex-state.sh show|dir|reset|reset --full|get|set.

State is isolated per git branch and per worktree, so parallel review sessions on different branches are safe, while config.env is shared at the repo root. On ESCALATE, the skill reads the review notes from {state-dir}/notes/{phase}-review-{N}.md and uses AskUserQuestion to offer the user one more iteration, an unlimited iteration count (--max-iter 999), or stopping the review with a final summary. When Codex requests changes twice in a row without new substance, the skill escalates to the user the same way rather than looping indefinitely.

Developers running Claude Code who want a structured, GPT-reviewed gate on both planning and implementation - particularly for changes where a second model's independent judgment on the approach and the resulting code is worth the extra review round-trip.