codex-review

name: codex-review description: "Requests an independent code review from OpenAI Codex CLI, critically evaluates its findings, applies warranted fixes, and re-reviews until clean. Activates when: the user says /codex-review, asks for a Codex review, or wants an external AI review of changes." metadata: schema-required: "^1"

Codex Code Review

Run an independent code review using OpenAI Codex, critically evaluate and apply warranted findings, and re-review after fixes until a round comes back clean.

Step 1: Determine what to review

Check what has changed:

git diff --stat HEAD
git diff --stat --staged

If there are uncommitted changes, review those. If the working tree is clean, review the latest commit. The exact invocation depends on the invocation mode below.

Step 2: Run Codex review

This project's Codex invocation mode is plugin. Follow the matching path below: plugin (the canonical path, default) or bare_cli (the opt-in fallback for environments where the plugin can't be installed).

Plugin path (invocation_mode: plugin, default)

The openai/codex-plugin-cc plugin ships a companion script (codex-companion.mjs) that wraps @openai/codex with background queueing, project-aware diff scoping, focus-argument handling, and stable file-based result retrieval. Two pieces must both be installed:

The skill never invokes codex directly — it calls the companion script (codex-companion.mjs) shipped by the plugin. The companion script wraps codex with the aforementioned ergonomics.

Plugin install

If /codex:review is not available in this session:

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

/codex:setup is the plugin's own one-time bootstrap; it confirms the companion script is reachable and walks through authentication.

Codex CLI install

If the companion script reports Codex CLI is not installed:

npm install -g @openai/codex

Requires a ChatGPT subscription (Free tier is sufficient) or an OpenAI API key. If the CLI is installed but not authenticated, the user can run codex login in their own terminal (suggest via !codex login from this session if you want the output captured here).

Companion script path

Resolve the latest installed copy at invocation time — version path varies as the plugin updates:

COMPANION=$(ls ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)

If the resolution returns nothing, the plugin is not installed — fall back to the Plugin install steps earlier in this skill.

Invocation patterns

Pick one of four shapes depending on review scope and whether the user supplied a focus argument:

Substitute <base> with the resolved base branch. Scan the configured branch patterns in declared order; the first pattern matching the current branch name wins, and its base field is the base:

<!--boost:conv path="branches.patterns" mode="yaml"-->none — no branch patterns configured<!--boost:conv:end-->

If no pattern matches (or none are configured), fall back to the default base branch main. Same resolution the pull-requests skill uses.

Always quote FOCUS as a shell variable — never interpolate user input directly into the command line.

Use adversarial-review whenever a focus argument is present; the bare review subcommand has no focus parameter.

Polling

The companion runs Codex in the background. Poll until the job leaves the running / queued state:

CODEX_TIMED_OUT=true
for i in $(seq 1 15); do
  sleep 20
  STATUS=$(node "$COMPANION" status 2>&1)
  if ! echo "$STATUS" | grep -qE "\| running \||\| queued \|"; then
    CODEX_TIMED_OUT=false
    break
  fi
  echo "Still running... ($i/15)"
done

15 iterations × 20 seconds = 5-minute ceiling. If the loop exits with CODEX_TIMED_OUT=true, the review has not completed.

Critical: if CODEX_TIMED_OUT=true, do NOT call result afterwards. The result subcommand returns the most recent finished job, which can be a stale unrelated review — applying that as if it were the current job will mix unrelated feedback into the conversation. Tell the user the review is still running and stop.

Retrieving results

Only when CODEX_TIMED_OUT=false:

node "$COMPANION" result 2>&1 || true

If the output mentions a file path (long reviews truncate in stdout), load the full content via the Read tool — don't try to scroll the truncated output.

Bare-CLI path (invocation_mode: bare_cli, opt-in fallback)

For environments where the plugin can't be installed (service-account CI runners with no per-user .claude/plugins/ cache, headless agents, locked-down environments), invoke codex directly. Install: npm install -g @openai/codex; auth: codex login (interactive, in the user's own terminal).

The scope flags (--uncommitted / --commit / --base) cannot be combined with a custom prompt — Codex runs its built-in review and picks up project context from AGENTS.md.

For uncommitted changes:

codex exec review --full-auto --uncommitted

For the latest commit:

codex exec review --full-auto --commit HEAD

For changes against a base branch (resolve <base> the same way as the plugin path — branch patterns first, then the default base branch):

codex exec review --full-auto --base <base>

Synchronous — review ties up the agent session for the full review window (typically 2-5 min). No background queueing or polling loop (those are plugin-only features). Stdout output can truncate on very long reviews; redirect to a file (> codex-review.out) if needed.

Cross-cutting concerns (apply identically under both invocation modes)

• Auth failure — if codex is installed but reports an auth failure (whether surfaced by the plugin's companion script or by bare-CLI directly), leave the review unrun and surface it to the user. Don't try to authenticate on their behalf — codex login is interactive and binds to their session.
• Capacity / transient failures — if the review fails on model capacity, rate limiting, or a transient error, retry the same command a few times with the same engine and model. Never substitute a different review engine or fall back to reviewing the code yourself under this skill's name — the whole value here is the independent second opinion. If retries keep failing, leave the review unrun and surface it to the user.
• Project-specific overrides doc — none — the path-specific playbooks above are self-contained. If a path is shown, load that file for project-specific overrides (custom auth flow, focus areas, exclusions) regardless of invocation mode. Most consumers leave it unset.
• pr.gates skill_invoked: codex-review interaction — if the codex review can't run (auth failure, plugin missing under invocation_mode: plugin, codex CLI missing under invocation_mode: bare_cli), the pr.gates on_missing: stop_and_request policy means the vendor pull-requests skill should leave the gate's checklist item unchecked + note the unrun-reason rather than blocking PR creation entirely.

Step 3: Critically evaluate findings

Codex findings are a second opinion, not gospel. You have greater context on the codebase — use it. For each finding:

1. Is it a real bug? — Verify by reading the code. Don't trust Codex's assessment blindly.
2. Is it already tested? — Check if existing tests cover the scenario.
3. Is it a style preference? — Skip. Don't change working code for style.
4. Is it a false positive? — Codex may misunderstand framework internals or the project's architecture. Verify against the actual behavior.
5. Does it conflict with the project's established patterns? — Check sibling files. Established project patterns take precedence over Codex preferences.

Don't over-apply: a review that implements 2 real improvements is better than one that applies 10 questionable changes. For each finding, briefly note whether you're implementing or skipping it and why.

Step 4: Apply warranted fixes

For findings that are genuine issues:

1. Fix the code
2. Sweep for siblings — when an accepted finding reveals a bug class or repeated pattern, check the rest of the reviewed scope for other instances and fix them in the same pass. Stay within the scope under review; instances elsewhere in the codebase are follow-up territory, not this change.
3. Verify with the project's tests and static analysis (see the backend-quality / frontend-quality skills for the relevant stack)

Step 5: Re-review until clean

A review is stale the moment a fix changes any file. If Step 4 changed any files, run the review again and repeat Steps 3–4 on the new findings. Loop until a round comes back clean: no warranted findings, where findings dismissed with reasoning count as handled. A review that predates the last file change is stale — the same staleness a pr.gates freshness window (window: since_last_code_change) guards against.

Re-review the change's current state, not the original target:

• Original scope was the uncommitted working tree → leave the round's fixes uncommitted and re-run the working-tree review; it covers the original change plus the fixes.
• Original scope was committed work (a commit or branch vs base) → commit the round's fixes first (Step 7 format), then re-review the full range including the fix commit — the same base for a branch review, or the originally reviewed commit's parent as base when a single commit was reviewed. Re-running the original mode unchanged would re-review the unfixed code and re-surface the same findings.

Stop rules:

• A clean round is final. Never run an extra review to confirm a clean result or to get a nicer closing line.
• A dismissals-only round is final. If a round changed no code (all findings dismissed), there is nothing to re-review — stop.
• Cap at 3 review rounds. If warranted findings keep surfacing after three rounds, stop and surface the remaining findings to the user rather than looping further.

Step 6: Report

Summarize to the user:

## Codex Review Summary

### Applied
- [Issue] — [What was wrong and how you fixed it]

### Dismissed
- [Finding] — [Why it was dismissed: false positive / already tested / style preference]

### No Issues
- [Categories that were clean]

Step 7: Commit (if changes were applied)

This step applies when the reviewed scope was committed work (a commit or branch vs base): commit the applied fixes separately so each review round stays traceable in git history. When the reviewed scope was the uncommitted working tree, leave the fixes uncommitted — they are part of the same in-progress change the user has not committed yet, and committing would sweep up unrelated work-in-progress. Only commit a working-tree review's fixes when the user explicitly asks.

Only list the implemented changes in the commit message — keep dismissed findings and their rationale in the conversation for the user's reference:

Apply codex-review feedback

- <brief description of an applied change>
- <brief description of another applied change>

If no fixes were applied (all findings were dismissed), do not create a commit — just report the outcome so the user knows.