ralphex-review

name	ralphex-review
description	Codex reviews, Claude filters and fixes, repeat until clean
argument-hint	Optionally describe what to focus the review on
disable-model-invocation	true
allowed-tools	Bash(*)

Ralphex Review: Iterative Code Review with Codex

Execute an iterative review loop where Codex reviews your existing code, you (Claude Code) filter the suggestions and implement fixes, then Codex reviews again. Loop until there is no relevant corrections to implement in Codex's review.

---

Step 1: Read Settings

1. Generate a session ID by running head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n' via Bash. Store the output as session_id.
2. Check if .claude/ralphex.local.md exists in the project root.
3. If it exists, read it and parse the YAML frontmatter to extract:
   • base_branch: The branch to diff against (default: main)
   • codex_model: The Codex model to use (REQUIRED - if missing, ask the user)
   • codex_reasoning_effort: Reasoning effort for Codex reviews (default: high)
4. If the file does not exist, first run command -v codex via Bash. If the command exits with a non-zero status (codex not found), inform the user: "Codex CLI is not installed. Install it from https://github.com/openai/codex and try again." and stop. Otherwise, ask the user:
   • What base branch to diff against (suggest main)
   • What Codex model to use (gpt-5.4, gpt-5.4-mini, gpt-5.5)
   • What reasoning effort to use for reviews (suggest high; valid values: low, medium, high, xhigh) Then create .claude/ralphex.local.md with their answers.\
5. Check for uncommitted changes by running git status. If there are uncommitted changes, use AskUserQuestion to present these options: a. Commit modified tracked files: Run git add -u to stage all modified tracked files. Ask the user for a commit message, then commit with that message. b. Commit all changes (modified + untracked): Run git add -A to stage everything including untracked files. Ask the user for a commit message, then commit with that message. c. Stash changes: Generate a unique stash name by running date +%s and using "ralphex-review-stash-{timestamp}". Run git stash push -m "ralphex-review-stash-{timestamp}". Store the full stash message for later cleanup. d. Cancel: Stop the review.
6. Resolve the review target: Run git rev-parse --abbrev-ref HEAD to get the current branch. Compute a review_target value:
   • If the current branch is different from base_branch, set review_target = base_branch.
   • If the current branch equals base_branch, check if origin/{base_branch} exists by running git rev-parse --verify origin/{base_branch}. If it exists, set review_target = origin/{base_branch}. If it does not exist, inform the user that there is no remote to compare against and stop.
   • Verify there is actually a diff by running git diff --stat {review_target}...HEAD. If the diff is empty, inform the user there are no changes to review and stop.

Store session_id, review_target, codex_model, and codex_reasoning_effort for use throughout the workflow. Use review_target (not base_branch) in all subsequent git and Codex commands.

---

Step 2: Codex Code Review

Run Codex to review the branch changes:

1. Run this command via Bash, replacing {review_target}, {codex_model}, and {codex_reasoning_effort} with the resolved values from Step 1, unless the user prompt "$ARGUMENTS" says otherwise:

   codex exec --sandbox read-only -m {codex_model} -c model_reasoning_effort="{codex_reasoning_effort}" -o /tmp/ralphex-review-{session_id}.txt "Review the committed changes of this branch against {review_target}. $ARGUMENTS" 2>/dev/null
   

2. Check the exit code. If the command exits with a non-zero status, inform the user that Codex failed (include the exit code). Perform Cleanup: Restore Stashed Changes if a stash was created in Step 1, then stop.

---

Step 3: Evaluate Review

Read the contents of /tmp/ralphex-review-{session_id}.txt.

If corrections exist, critically evaluate each one

Do NOT blindly accept all suggestions. Codex can be wrong, pedantic, or suggest changes outside the task scope. For each suggestion in the review, independently evaluate and classify it:

• Accept: Real bugs, security issues, correctness problems, or clear improvements directly related to the task. These will be addressed in the next iteration.
• Reject: Factually wrong suggestions, misunderstandings of the code or requirements, or purely stylistic preferences that don't improve correctness.
• Defer: Valid observations that are out of scope for the current task (e.g., pre-existing issues, unrelated refactoring suggestions).

Display your verdicts to the user in this format:

**Iteration {N} - Codex Review Evaluation:**
- ✅ Accept: {summary of accepted suggestion}
- ❌ Reject: {summary and reason for rejection}
- ⏭️ Defer: {summary and reason for deferral}

Then decide:

• If all suggestions are rejected or deferred → treat this as a clean review. Inform the user. Perform Cleanup: Restore Stashed Changes if a stash was created in Step 1, then stop.
• If any suggestions are accepted → proceed to Step 4: Implement with only the accepted corrections. Do not address rejected or deferred items.

If clean

• Inform the user that Codex approved the implementation
• Display the total number of iterations it took
• Perform Cleanup: Restore Stashed Changes if a stash was created in Step 1.

---

Step 4: Implement

Implement the accepted corrections:

1. For each accepted correction, explore the relevant code to understand the context.
2. Make the necessary code changes. Keep changes focused: only address accepted corrections, do not refactor unrelated code.
3. Verify changes are consistent with the rest of the codebase.

---

Step 5: Commit

Create a clean git state for Codex to review again:

1. Stage all changed files with git add (be specific about which files. Do NOT use git add . or git add -A).
2. Commit with a descriptive message summarizing what was fixed based on the Codex review.
3. Verify changes are committed with git status.

After committing, go back to Step 2: Codex Code Review for the next iteration.

---

Cleanup: Restore Stashed Changes

If a stash was created in Step 1, restore it before stopping:

1. Run git stash list and find the entry whose message contains the stash name stored in Step 1 (e.g., "ralphex-review-stash-{timestamp}").
2. Extract its stash@{N} reference from the matching line.
3. Run git stash pop stash@{N}.
4. If the pop fails due to conflicts, inform the user that the stash could not be applied cleanly and tell them to resolve conflicts and run git stash pop manually.

---

Important Rules

• Never skip the commit step. Codex reviews committed diffs.
• Track iteration count. Display it with each review cycle so the user knows progress.
• The loop is fully automatic. No user approval is needed between iterations. Only stop when Codex gives a clean review, or all suggestions are rejected/deferred.
• If Codex CLI fails (command not found, network error, etc.), inform the user and stop. Do not retry automatically.
• The workspace must be clean before the first review. Codex reviews committed diffs. If there are uncommitted changes, offer to commit them, stash them, or cancel.
• If changes were stashed, always restore them. Every exit path must perform the Cleanup: Restore Stashed Changes step before stopping.