How I Automated Codex Code Reviews for Both Claude Code and Codex

## Codex Review (BEFORE committing) — MANDATORY

After completing each task (all tests passing, implementation done),
but **before any commit**:

1. Launch 3 independent native Codex reviews of the current uncommitted changes:

   codex review --uncommitted

   Do not pass a prompt or extra instructions. The native command already
   knows how to review the uncommitted working tree.

   Prefer the local wrapper when running the required three-review round:

   ~/bin/codex-review-run --scope uncommitted --triple

   The wrapper only automates three independent `codex review --uncommitted`
   runs and stores the outputs under `~/.codex/review-runs/<timestamp>/`.

2. Collect all 3 final reviewer outputs from `~/.codex/review-runs/<timestamp>/`.
   Use the helper script to print only the final Codex output block:

   python3 scripts/reviews/extract-final-codex-review.py \
       ~/.codex/review-runs/<timestamp>/review-*.raw.txt

3. Validate each review is real:
   - A clean review must explicitly say there are no actionable in-scope findings.
   - A review with findings usually includes `Review comment:` or
     `Full review comments:` plus prioritized findings.
   - If the output is just a status stub or malformed, re-run it.

4. Every review round is a FULL FRESH review — never scope Codex to
   "just check my fixes." Each round reviews ALL uncommitted changes from scratch.

5. Merge and deduplicate findings from all 3 reviews into a single list.

6. Evaluate findings critically — Codex may lack full context, so assess each issue.
   - If two of the three reviews are clean and the remaining review only finds
     a low-severity issue (P3), treat the round as clean after documenting that.

7. Fix real issues identified by Codex.

8. Run three fresh `codex review --uncommitted` reviews again after fixing.
   A skip in the task change set is NOT a pass.

9. Repeat until the task change set has no actionable in-scope issues.

10. Only a clean Codex review for the task change set allows committing.

#!/usr/bin/env bash

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  codex-review-run --scope uncommitted [--runs 1|3] [--prompt "text"]
  codex-review-run --scope base --base main [--runs 1|3] [--prompt "text"]
  codex-review-run --scope commit --commit <sha> [--runs 1|3] [--prompt "text"]

This is a plain wrapper around `codex review`. It is not a Codex skill.
It saves review artifacts under ~/.codex/review-runs/<timestamp>/.

Options:
  --triple   Shortcut for --runs 3
  --notify   Send a macOS notification when all review runs finish
EOF
}

scope=""
runs="3"
base_ref=""
commit_sha=""
prompt=""
label=""
notify="0"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --scope)
      scope="${2:-}"
      shift 2
      ;;
    --runs)
      runs="${2:-}"
      shift 2
      ;;
    --base)
      base_ref="${2:-}"
      shift 2
      ;;
    --commit)
      commit_sha="${2:-}"
      shift 2
      ;;
    --prompt)
      prompt="${2:-}"
      shift 2
      ;;
    --label)
      label="${2:-}"
      shift 2
      ;;
    --triple)
      runs="3"
      shift
      ;;
    --notify)
      notify="1"
      shift
      ;;
    --help|-h)
      usage
      exit 0
      ;;
    *)
      echo "Unknown argument: $1" >&2
      usage >&2
      exit 1
      ;;
  esac
done

if [[ -z "$scope" ]]; then
  echo "--scope is required" >&2
  usage >&2
  exit 1
fi

if [[ "$runs" != "1" && "$runs" != "3" ]]; then
  echo "--runs must be 1 or 3" >&2
  exit 1
fi

case "$scope" in
  uncommitted)
    ;;
  base)
    [[ -n "$base_ref" ]] || { echo "--base is required for --scope base" >&2; exit 1; }
    ;;
  commit)
    [[ -n "$commit_sha" ]] || { echo "--commit is required for --scope commit" >&2; exit 1; }
    ;;
  *)
    echo "--scope must be one of: uncommitted, base, commit" >&2
    exit 1
    ;;
esac

command -v codex >/dev/null 2>&1 || { echo "codex CLI not found on PATH" >&2; exit 1; }

timestamp="$(date +"%Y%m%d-%H%M%S")"
run_dir="${HOME}/.codex/review-runs/${timestamp}"
mkdir -p "$run_dir"

cat >"${run_dir}/meta.env" <<EOF
timestamp=${timestamp}
cwd=$(pwd)
scope=${scope}
runs=${runs}
base_ref=${base_ref}
commit_sha=${commit_sha}
label=${label}
notify=${notify}
EOF

run_one() {
  local idx="$1"
  local raw_file="${run_dir}/review-${idx}.raw.txt"
  local exit_file="${run_dir}/review-${idx}.exitcode"
  local -a cmd

  cmd=(-c features.plugins=false review)
  case "$scope" in
    uncommitted) cmd+=(--uncommitted) ;;
    base) cmd+=(--base "$base_ref") ;;
    commit) cmd+=(--commit "$commit_sha") ;;
  esac

  {
    echo "# review ${idx}"
    echo "# cwd: $(pwd)"
    echo "# scope: ${scope}"
    [[ -n "$base_ref" ]] && echo "# base_ref: ${base_ref}"
    [[ -n "$commit_sha" ]] && echo "# commit_sha: ${commit_sha}"
    [[ -n "$label" ]] && echo "# label: ${label}"
    [[ -n "$prompt" ]] && echo "# prompt: ${prompt}"
    echo
  } >"$raw_file"

  if [[ -n "$prompt" ]]; then
    codex "${cmd[@]}" "$prompt" >>"$raw_file" 2>&1
  else
    codex "${cmd[@]}" >>"$raw_file" 2>&1
  fi

  echo "$?" >"$exit_file"
}

declare -a pids=()
for idx in $(seq 1 "$runs"); do
  run_one "$idx" &
  pids+=("$!")
done

failed=0
for pid in "${pids[@]}"; do
  if ! wait "$pid"; then
    failed=1
  fi
done

{
  echo "run_dir=${run_dir}"
  for idx in $(seq 1 "$runs"); do
    echo "review_${idx}_raw=${run_dir}/review-${idx}.raw.txt"
    echo "review_${idx}_exitcode=$(cat "${run_dir}/review-${idx}.exitcode" 2>/dev/null || echo "missing")"
  done
} >"${run_dir}/manifest.txt"

echo "${run_dir}"

if [[ "$notify" == "1" ]] && command -v osascript >/dev/null 2>&1; then
  if [[ "$failed" -eq 0 ]]; then
    osascript -e 'display notification "Codex review runs finished" with title "Codex Review"' >/dev/null 2>&1 || true
  else
    osascript -e 'display notification "Codex review runs finished with failures" with title "Codex Review"' >/dev/null 2>&1 || true
  fi
fi

if [[ "$failed" -ne 0 ]]; then
  exit 1
fi

#!/usr/bin/env python3

from __future__ import annotations
import argparse
from pathlib import Path

DEFAULT_FALLBACK_LINES = 120


def extract_review_output(path: Path, fallback_lines: int) -> str:
    lines = path.read_text(encoding="utf-8").splitlines()
    if not lines:
        raise ValueError("empty review file")

    codex_index = None
    for index, line in enumerate(lines):
        if line.strip() == "codex":
            codex_index = index

    if codex_index is not None:
        return "\n".join(lines[codex_index:]) + "\n"

    return "\n".join(lines[-fallback_lines:]) + "\n"


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Print the final Codex review output from one or more raw review files."
    )
    parser.add_argument("paths", nargs="+", help="One or more review-*.raw.txt files")
    parser.add_argument("--fallback-lines", type=int, default=DEFAULT_FALLBACK_LINES)
    args = parser.parse_args()

    exit_code = 0
    for index, raw_path in enumerate(args.paths):
        path = Path(raw_path)
        if len(args.paths) > 1:
            if index > 0:
                print()
            print(f"=== {path}")
        try:
            print(extract_review_output(path, args.fallback_lines), end="")
        except Exception as error:
            exit_code = 1
            print(f"[extract-final-codex-review] {error}")

    return exit_code


if __name__ == "__main__":
    raise SystemExit(main())

---
name: cc-3parallel-codex-reviews
description: Run 3 parallel Codex code reviews on the uncommitted working tree via the Codex companion runtime, returning clean Markdown findings per reviewer. Use for pre-commit review gates, or when the user asks to "codex-review", "run 3 parallel reviews", or "check my uncommitted changes with Codex". Each reviewer's output is ~50 clean lines of findings (no raw-transcript extraction needed).
allowed-tools: Bash, Read
---

# 3 Parallel Codex Reviews

Launches three independent Codex reviews against the uncommitted working tree by invoking the same companion runtime that backs the `/codex:review` slash command. Each review runs as its own background Bash task, so each produces its own completion notification and its own clean-Markdown output_file.

## Preconditions

Before step 1, verify:

- `node` is on `PATH`.
- Codex companion script exists at `~/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs` (it's installed as part of the `openai-codex` plugin). If missing, stop and tell the user to install the Codex plugin.
- Working tree has uncommitted changes → `git status --short` must be non-empty. If empty, there is nothing to review — tell the user and stop.

## Procedure

### Step 1 — Launch 3 reviews in parallel

Three **separate** Bash tool calls, each with `run_in_background: true`, each running:

```bash
node "$HOME/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs" review --wait --scope working-tree
```

Why the companion directly (not the slash command): `/codex:review` has `disable-model-invocation: true` and cannot be invoked by agents via the Skill tool. The companion script is the exact thing the slash command wraps.

Why three separate Bash calls (not a loop inside one Bash): each call gives its own completion notification with its own `output_file`. A single-Bash fan-out (like the `--triple` wrapper) yields one combined notification instead.

### Step 2 — Wait for 3 completion notifications

Do not poll. Do not call `BashOutput`. Do not read files early. Just wait. The harness will send three `task-notification` messages — one per background Bash call — as they complete (typically ~60–120 s each).

### Step 3 — Read each output_file

For each of the three notifications, use the `Read` tool on the notification's `output_file` path. Each output_file contains the companion's clean Markdown output, which looks like:

```
[codex] Starting Codex review thread.
[codex] ...
[codex] Turn completed.
# Codex Review

Target: working tree diff

<summary paragraph>

Full review comments:

- [P2] <title> — <absolute file path>:<line-range>
  <explanation>

Reasoning:
- ...
```

The `[codex]` progress log is a compact one-line-per-step trace (useful for verifying the review actually ran). The `# Codex Review` section is the structured output. The `Reasoning:` trailer is optional context from the reviewer's thoughts.

### Step 4 — Merge, dedupe, and surface

Surface to the user:

- **Per-review verdict**: zero-issues vs issues-found.
- **Deduplicated unique findings** across all 3 reviews, each with file:line citation and severity (`P0`/`P1`/`P2`/`P3`). Findings flagged by multiple reviewers are higher-confidence.
- **Your triage**: real vs false-positive, with reason. A finding is almost certainly a false positive if its cited file/line is **not** in `git status --short` — that means the reviewer explored an out-of-scope artifact (stale review output, unrelated committed code, etc.).
- **Recommended fixes** per real finding, including the test you'd add.

## What NOT to do

- **Do not** invoke `/codex:review`, `/codex:adversarial-review`, `/codex:status`, or `/codex:result` from the Skill tool — all are `disable-model-invocation: true` and the Skill tool will reject them. Those slash commands are user-typed only.
- **Do not** use `~/bin/codex-review-run --triple` — it fans out inside a single Bash call, so the agent gets one combined notification instead of three per-reviewer notifications.
- **Do not** spawn `Agent(subagent_type: ...)` subagents for the reviewer. Subagent sandboxes typically block both `/codex:review` (via `disable-model-invocation`) and Bash access to the `codex` binary, so the review never actually runs.
- **Do not** pass a custom prompt to the companion. The canonical workflow is no-prompt. Context the reviewer needs (project rules, library docs, design system) should live in persistent files the reviewer finds through its own diff exploration — not in per-run prompts.
- **Do not** act on findings during the review. This skill is read-only — surface findings to the user; let them decide. The triage step is read-only too (classifying findings, not fixing code).

## Why three reviews, not one

A single `codex review` pass has reasoning variance: different runs on the same diff surface different subsets of issues. Three independent runs caught as a union approach complete coverage. Empirically ~90% of findings are real; if only one of three reviewers flags an issue, still treat it as real and triage on its merits rather than by vote count.

## Filesystem contamination

Codex reviewers run in `danger-full-access` and do exploratory `grep`/`find` across accessible paths. Old review artifacts under `~/.codex/review-runs/` (left behind by the human `codex-review-run --triple` wrapper) can contaminate findings — the reviewer tails them and may cite content from a *prior* session as a current issue.

Mitigations:

- If contamination starts polluting findings, move old artifacts *out* of `~/.codex/`: `mv ~/.codex/review-runs ~/codex-review-archive-$(date +%s)`. Renaming to `~/.codex/review-runs.archive/` does **not** work — the reviewer still follows the renamed path.
- Always verify that finding-cited file paths are in `git status --short`. If a finding cites a file that is not in the uncommitted diff, it is almost certainly out-of-scope contamination.

## Scope variants

Swap the `--scope` flag for different review scopes. Everything else in the procedure stays identical:

| Scope flag | Meaning | When to use |
|---|---|---|
| `--scope working-tree` | Uncommitted staged + unstaged + untracked | Per-task pre-commit loop (skill default) |
| `--scope branch` | Branch vs default base ref (`main`/`develop`) | PR-level review before merge |
| `--scope branch --base <ref>` | Branch vs a specific base | Reviewing against a non-default base |

If the user asks for a non-default scope, swap the flag in step 1 and keep everything else identical.