codex-review

Codex Review

Code review via the codex plugin companion script. Runs codex review, collects results, and synthesizes findings.

Codex Plugin Companion Script

The codex plugin provides a companion script for running reviews. Resolve it dynamically:

CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"

If the directory or file does not exist, report "Codex plugin not installed. Run /codex:setup first." and fall back to Claude Code review.

Usage:

node "$CODEX_COMPANION" review --base <branch> --wait

Key flags:

• --base <branch>: Review changes against this base branch
• --wait: Run in foreground (block until complete)
• --scope auto|working-tree|branch: Scope selection (default: auto)

Process

Step 0: Pre-flight Rate Limit Check

Before doing anything, check if Codex is currently rate-limited:

RATE_CHECK=$(node $HOME/.claude/scripts/codex-rate-limit.js check 2>&1)
RATE_EXIT=$?

If RATE_EXIT is non-zero (rate-limited), skip all codex steps and jump directly to the Fallback step. Do NOT report the rate limit to the user — silently fall back.

Step 1: Determine Base Branch

BRANCH=$(git branch --show-current)
BASE=$(gh pr view --json baseRefName -q '.baseRefName' 2>/dev/null)

If no PR, use default branch:

BASE=$(git remote show origin | grep 'HEAD branch' | awk '{print $NF}')

Step 2: Prepare Environment

LOGDIR=$(node $HOME/.claude/scripts/get-logdir.js)
mkdir -p "$LOGDIR"
DATETIME=$(date +%Y%m%d_%H%M%S)

# Resolve codex companion script (pick latest version if multiple exist)
CODEX_PLUGIN_ROOT=$(command ls -d "$HOME/.claude/plugins/cache/openai-codex/codex"/*/ 2>/dev/null | sort -V | tail -1)
CODEX_COMPANION="${CODEX_PLUGIN_ROOT}scripts/codex-companion.mjs"

# Detect timeout command (gtimeout on macOS via coreutils, timeout on Linux/WSL)
if command -v gtimeout &>/dev/null; then
  TIMEOUT_CMD="gtimeout"
elif command -v timeout &>/dev/null; then
  TIMEOUT_CMD="timeout"
else
  TIMEOUT_CMD=""
  echo "WARNING: neither gtimeout nor timeout found. Running without timeout."
fi

Use $DATETIME in all output filenames below to avoid overwriting previous runs.

Step 3: Run Codex Review

Run the companion script's review command with --base and --wait:

${TIMEOUT_CMD:+$TIMEOUT_CMD} ${TIMEOUT_CMD:+1500} node "$CODEX_COMPANION" review --base "$BASE" --wait \
  > "$LOGDIR/${DATETIME}-codex-review.md" \
  2>"$LOGDIR/${DATETIME}-codex-review-stderr.log"

Launch as a background Bash task with a 25-minute timeout.

Step 4: Collect Results and Check for Rate Limiting

After codex completes (or times out):

1. Check for rate limiting in the output files:

   node $HOME/.claude/scripts/codex-rate-limit.js check-output \
     "$LOGDIR/${DATETIME}-codex-review.md" \
     "$LOGDIR/${DATETIME}-codex-review-stderr.log"
   

   If exit code is non-zero (rate limit detected), jump to Fallback.

2. Check the output file ($LOGDIR/${DATETIME}-codex-review.md) exists and has content

3. If missing or empty, read the stderr log ($LOGDIR/${DATETIME}-codex-review-stderr.log) to diagnose why

4. Report any stderr contents to the user (auth errors, API failures, etc.)

Step 5: Fallback — Opus

If codex timed out, produced no output, or is rate-limited:

• Silently fall back to Opus — do NOT report the rate limit or timeout to the user. Do NOT pause the workflow.
• Spawn 2 code-reviewer subagents in parallel (like /light-review) with model: opus, reviewing the diff against $BASE. Opus is the designated Claude-side stand-in for codex: roughly comparable quality, no quota-loud failure mode.
• Continue the workflow as if /light-review was invoked instead

Step 6: Synthesize and Report

1. Read codex output and organize findings
2. Categorize by priority (high / medium / low)
3. Present a clear summary to the caller
4. Include log file paths for reference

Step 7: Apply Fixes

• High priority: Implement automatically
• Medium priority: Implement if clearly safe, otherwise ask
• Low priority: Ask user

Step 8: Commit Changes

If fixes were applied, commit with a descriptive message.

Timeout Policy

• Timeout: 25 minutes (1500s via gtimeout/timeout command, auto-detected)
• If codex times out: Silently fall back to Opus (2 code-reviewer subagents with model: opus)

Important Notes

• Codex runs in read-only sandbox by default for reviews — it cannot modify files
• All file writing and editing is done by Claude Code, never by codex
• Output files go to $LOGDIR/${DATETIME}-codex-review-*.md (timestamped to avoid overwrites)
• Stderr logs go to $LOGDIR/${DATETIME}-codex-review-*-stderr.log (for debugging silent failures)
• This skill is preferred over /light-review for code review tasks
• Silent fallback policy: If codex is rate-limited, timed out, or unavailable for any reason, silently fall back to Opus (2 code-reviewer subagents at model: opus, like /light-review). NEVER pause the workflow, NEVER report the rate limit to the user, NEVER ask what to do. Just continue with the fallback as if nothing happened. Opus is the designated Claude-side stand-in for codex throughout these skills — the user already chose -co to mean "give me the better reviewer," so dropping to Opus matches the spirit of that choice when codex is unavailable