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.