ralphex

name	ralphex
description	Claude implements, Codex reviews, repeat until clean
argument-hint	Describe the coding task to implement
disable-model-invocation	true
allowed-tools	Bash(*)

Ralphex: Iterative Development with Codex Code Review

Execute an iterative development loop where you (Claude Code) plan and implement code, then Codex reviews your work. Loop until there is no relevant corrections to implement in Codex's review.

User's task: $ARGUMENTS

---

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. 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: Plan

This step has two modes depending on whether this is the first iteration or a subsequent one.

First iteration — Plan Mode

On the first iteration, use Claude Code's native plan mode to explore, design, and get user approval before implementing.

1. Call EnterPlanMode to transition into read-only plan mode.
2. Create a plan. If the user prompt was vague or incomplete, ask clarifying questions by using AskUserQuestion.
3. Call ExitPlanMode to present the plan to the user for approval.
4. If the user rejects or requests changes, revise the plan and call ExitPlanMode again. Do not proceed until approved.

Subsequent iterations — Lightweight Re-plan

On subsequent iterations (after a Codex review with accepted corrections):

1. Incorporate only the accepted Codex corrections into a targeted re-plan.
2. Avoid full re-exploration, but do focused exploration (Read, Grep, Glob) when accepted corrections reference files or code paths not inspected in the first iteration.
3. No user approval is needed, proceed immediately to implementation.

---

Step 3: Implement

Execute the implementation plan:

1. Write or modify the necessary code files.
2. Make sure the implementation is complete and functional.
3. If you encounter issues, resolve them as part of the implementation.

---

Step 4: Commit

Create a clean git state for Codex to review:

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. Use this format:
   • First iteration: A message describing the initial implementation
   • Subsequent iterations: A message describing what was fixed based on Codex review
3. Verify changes are committed with git status

---

Step 5: Codex Code Review

1. Run this exact command via Bash:

   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}." 2>/dev/null
   

   Replace {review_target}, {codex_model}, and {codex_reasoning_effort} with the resolved values from Step 1.

2. Check the exit code. If the command exits with a non-zero status, inform the user that Codex failed (include the exit code), then stop.

---

Step 6: 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 and stop.
• If any suggestions are accepted → go back to Step 2: Plan with only the accepted corrections as context. 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

---

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 initial plan requires user approval. Do not begin implementation until the user approves the plan via ExitPlanMode.
• Plan mode is only for the first iteration. Do not call EnterPlanMode on subsequent iterations. The lightweight re-plan runs inline without plan mode.
• If Codex CLI fails (command not found, network error, etc.), inform the user and stop. Do not retry automatically.