ralphex

Quick Start

Make sure ralphex is installed and your project is a git repository. You need a plan file in docs/plans/, for example:

# Plan: My Feature

## Validation Commands
- `go test ./...`

### Task 1: Implement feature
- [ ] Add the new functionality
- [ ] Add tests

Then run:

ralphex docs/plans/my-feature.md

ralphex will create a branch, execute tasks, commit results, run multi-phase reviews, and move the plan to completed/ when done.

How It Works

ralphex executes plans in four phases with automated code reviews, plus an optional finalize step.

Phase 1: Task Execution

1. Reads plan file and finds first incomplete task (### Task N: with - [ ] checkboxes)
2. Sends task to Claude Code for execution
3. Runs validation commands (tests, linters) after each task
4. Marks checkboxes as done [x], commits changes
5. Repeats until all tasks complete or max iterations reached

Steering mid-run: Press Ctrl+\ (SIGQUIT) during a task iteration to pause execution. ralphex cancels the current Claude session and prompts "press Enter to continue, Ctrl+C to abort". While paused, you can edit the plan file — on Enter, the same task re-runs with a fresh session that re-reads the plan. Press Ctrl+C to abort cleanly. Not available on Windows.

Phase 2: First Code Review

Launches 5 review agents in parallel via Claude Code Task tool:

| Agent | Purpose | |-------|---------| | quality | bugs, security issues, race conditions | | implementation | verifies code achieves stated goals | | testing | test coverage and quality | | simplification | detects over-engineering | | documentation | checks if docs need updates |

Claude verifies findings, fixes confirmed issues, and commits.

Default agents provide common, language-agnostic review steps. They can be customized and tuned for your specific needs, languages, and workflows. See Customization for details.

Phase 3: External Review (optional)

1. Runs external review tool (codex by default, or custom script)
2. Claude evaluates findings, fixes valid issues
3. Iterates until no open issues

The loop terminates when: all issues resolved, max iterations reached, stalemate detected (via --review-patience), or manual break via Ctrl+\ (SIGQUIT).

Stalemate detection: When the external tool and Claude can't agree on findings, the loop can waste tokens iterating to the max. Set --review-patience=N (or review_patience in config) to terminate after N consecutive rounds with no commits or working tree changes.

Manual break: Press Ctrl+\ (SIGQUIT) during the external review loop to terminate it immediately. The current executor run is cancelled via context cancellation. During the task phase, Ctrl+\ pauses instead — see Phase 1: Task Execution. Not available on Windows.

Supported tools:

• codex (default): OpenAI Codex for independent code review
• custom: Your own script wrapping any AI (OpenRouter, local LLM, etc.)
• none: Skip external review entirely

See Custom External Review for details on using custom scripts.

Phase 4: Second Code Review

1. Launches 2 agents (quality + implementation) for final review
2. Focuses on critical/major issues only
3. Iterates until no issues found
4. Moves plan to completed/ folder on success

Second review agents are configurable via prompts/review_second.txt.

Finalize Step (optional)

After all review phases complete successfully, ralphex can run an optional finalize step. Disabled by default.

What it does: runs a single Claude Code session with a customizable prompt. The default finalize.txt prompt rebases commits onto the default branch and optionally squashes related commits into logical groups.

How to enable:

Set finalize_enabled = true in ~/.config/ralphex/config or .ralphex/config.

Behavior:

• Runs once (no iteration loop)
• Best-effort — failures are logged but don't block success
• Triggers on modes with review pipeline: full, review-only, external-only
• Uses task color (green) for output

Customization:

Edit ~/.config/ralphex/prompts/finalize.txt (or .ralphex/prompts/finalize.txt) to change what happens after reviews. Examples: push to remote, send notifications, run deployment scripts, or any post-completion automation. Template variables like {{DEFAULT_BRANCH}} are available.

Review-Only Mode

Review-only mode (--review) runs the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already present on the current branch. This is useful when changes were made outside ralphex — via Claude Code's built-in plan mode, manual edits, other AI agents, or any other workflow.

Workflow:

1. Make changes on a feature branch (using any tool or workflow)
2. Commit the changes
3. Run ralphex --review

ralphex compares the branch against the default branch (git diff master...HEAD), launches multi-agent reviews, and iterates fixes until all agents report clean. No plan file is required — if provided, it gives reviewers additional context about the intended changes.

# switch to feature branch with existing changes
git checkout feature-auth

# run review pipeline on those changes
ralphex --review

# optionally pass a plan file for context
ralphex --review docs/plans/add-auth.md

Worktree Isolation

The --worktree flag runs plan execution in an isolated git worktree at .ralphex/worktrees/<branch>, enabling parallel execution of multiple plans on the same repo without branch conflicts.

Supported modes: --worktree only applies to full mode and --tasks-only. It is silently ignored for --review, --external-only, and --plan — these modes operate from the current directory.

Re-running reviews on a worktree branch: if the task phase completed in a worktree but the review phase needs to be re-run, cd into the worktree directory and run the review from there:

# find the worktree
ls .ralphex/worktrees/

# run review from inside it
cd .ralphex/worktrees/my-feature-branch
ralphex --review
# or
ralphex --external-only

Worktrees are automatically removed on successful completion. If a run is interrupted, the worktree directory may remain and can be reused or removed manually.

Plan Creation

Plans can be created in several ways:

• Claude Code - use slash commands like /ralphex-plan or your own planning workf