codex-review

name	codex-review
description	Autonomous review loop — Codex CLI reviews, Claude refines, iterating to convergence. Trigger phrases: "codex review", "review this", "get a second opinion".
disable-model-invocation	true
argument-hint	[file-path]

Codex Review

Autonomous iterative review loop: send a file to Codex CLI for review, refine based on feedback, and repeat until the reviewer has no further substantive feedback.

Currently supports plan review (references/plan.md). The loop is generic — new artifact types can be added by creating a new profile in references/.

When to Use

• After creating an implementation plan
• "codex review this", "review this plan", "get a second opinion"

Workflow

Phase 1: Identify and Prepare

Variables used throughout:

• FILE_STEM — the filename without extension (e.g. caching-layer-migration)
• FILE_NAME — the full filename (e.g. caching-layer-migration.md)

Select a review profile. Each profile is a file in references/ that must define:

1. Discovery — how to locate the artifact from $ARGUMENTS (or without arguments)
2. Artifact handling — where to copy the file, how to derive FILE_STEM/FILE_NAME
3. Review directory — where to store run artifacts (snapshots, patches, reviews)
4. Review criteria — what dimensions to evaluate and in what order
5. Prompt template — the review prompt for round 0

Available profiles:

• references/plan.md — implementation plans (from ~/.claude/plans/ or docs/plans/)
• references/implementation.md — code implementations reviewed against their plan

If no profile matches the artifact, ask the user which profile to use. Do not attempt to review without a profile — the review criteria are what make feedback actionable.

Identify the target file using the selected profile's discovery instructions and $ARGUMENTS.

Set up the run directory:

Generate a timestamp with second-level precision to avoid collisions. The review directory location is defined by the profile.

TIMESTAMP=$(date +%Y%m%dT%H%M%S)
RUN_DIR="<profile-defined-review-dir>/${FILE_STEM}/${TIMESTAMP}"
mkdir -p "${RUN_DIR}"
cp "<target-file>" "${RUN_DIR}/0.md"

Phase 2: Review Loop

Pre-flight checks:

1. Verify codex is in PATH. If not, report the error and exit:

   command -v codex >/dev/null 2>&1
   

2. Determine project root:

   PROJECT_ROOT=$(git rev-parse --show-toplevel)
   

Build the review prompt from the selected profile's prompt template and review criteria. Every review prompt should:

• Tell Codex to read the file at the given path
• Tell Codex to read the project's CLAUDE.md or AGENTS.md for context
• Provide the profile's evaluation criteria
• Ask for an overall assessment

Round 0 — initial review:

1. Run Codex with --json to capture the session ID:

   codex exec \
     -C "${PROJECT_ROOT}" \
     --full-auto \
     --json \
     -o "${RUN_DIR}/0-review.md" \
     "<REVIEW_PROMPT>" \
     > >(tee "${RUN_DIR}/0.jsonl") 2>"${RUN_DIR}/0.stderr"
   

   Sandboxed environments: If --full-auto fails because the environment is already externally sandboxed (e.g., Docker, CI), use --dangerously-bypass-approvals-and-sandbox instead. These two flags conflict and cannot be used together. Confirm with the user before switching to the bypass flag.

2. Parse the session ID from the JSONL output — look for the {"type":"thread.started","thread_id":"..."} event and extract thread_id. Store as SESSION_ID.

3. Read ${RUN_DIR}/0-review.md.

4. Interpret convergence: if Codex has no substantive feedback — only praise, minor cosmetic notes, or an explicit "looks good" — the review has converged. Proceed to Phase 3.

Round N (N >= 1):

1. Refine the artifact. Edit the target file based on Codex's feedback. Use judgment: accept improvements that strengthen the artifact, reject speculative bloat, answer clarifying questions by adding missing context.

2. Save the patch:

   diff -u "${RUN_DIR}/$((N-1)).md" "<target-file>" > "${RUN_DIR}/${N}.patch"
   

3. Snapshot current state:

   cp "<target-file>" "${RUN_DIR}/${N}.md"
   

4. Resume the Codex session (no -C — the session inherits its working directory from round 0):

   codex exec resume "${SESSION_ID}" \
     --full-auto \
     -o "${RUN_DIR}/${N}-review.md" \
     "I've updated the file based on your feedback. Please review the updated version at <target-path>."
   

5. Read ${RUN_DIR}/${N}-review.md and interpret convergence. Repeat or proceed to Phase 3.

Stall detection:

If two consecutive rounds produce feedback on substantially the same points AND Claude's refinements actually addressed those points (the artifact changed but Codex still raises the same concern), treat as converged — the disagreement is a matter of judgment, not a fixable gap.

If the feedback repeats because Claude failed to address it, that is not a stall. Claude should try a different approach to the same issue.

Oscillation:

If Codex reverses a suggestion it made in a prior round, make a judgment call — don't ping-pong.

Error handling:

• Non-zero codex exec exit: read any partial output, report the error, and ask the user whether to retry the round or abort
• Codex not installed: report with install instructions and exit

Working tree safety:

Codex exec runs with full file access and may modify or commit files in the working tree during its review (especially with --full-auto or --dangerously-bypass-approvals-and-sandbox). If you are making edits between rounds while Codex runs in the background, be aware that Codex may commit the working tree state — including your in-progress changes. Prefer sequential execution (wait for Codex to finish before editing) over concurrent edits.

Phase 3: Finalize

When converged:

1. Summary. Present: number of review rounds, key changes made across all rounds, and any feedback that was deliberately not incorporated (with reasoning).

2. Lessons learned. Review the full review history for patterns worth codifying — blind spots Codex repeatedly caught, non-obvious project context that surfaced, recurring weaknesses. Present these findings and suggest the user persist them as durable guardrails (tests, linter rules, documentation, or other appropriate mechanisms).

3. Durable outputs:

   • The reviewed artifact (updated in place)
   • ${RUN_DIR}/ — full review history for this run