ralphex - Autonomous Plan Execution

SCOPE: This command ONLY launches ralphex, monitors progress, and reports status. Do NOT take any other actions.

Step 0: Verify CLI Installation

Check if ralphex CLI is installed:

bash
which ralphex

If not found, guide installation based on platform:

• macOS (Homebrew): brew install umputun/apps/ralphex
• Linux (Debian/Ubuntu): download .deb from https://github.com/umputun/ralphex/releases
• Linux (RHEL/Fedora): download .rpm from https://github.com/umputun/ralphex/releases
• Any platform with Go: go install github.com/umputun/ralphex/cmd/ralphex@latest

Use AskUserQuestion to confirm installation method, then guide through it. Do not proceed until which ralphex succeeds.

Step 1: Check for Plan Argument

Check $ARGUMENTS for optional plan file path:

• if argument provided: validate file exists using Read tool, skip plan selection in Step 3
• if no argument: will ask for plan selection in Step 3

Step 2: Ask Execution Mode

Use AskUserQuestion:

• header: "Mode"
• question: "Which execution mode should ralphex use?"
• options:
• label: "Full (Recommended)"

description: "Task execution + Claude review + Codex loop + final Claude review"

• label: "Review"

description: "Skip tasks, run full review pipeline (Claude + Codex + Claude)"

• label: "Codex-only"

description: "Skip tasks and first Claude review, run only Codex loop"

Step 3: Plan Selection (if no argument provided)

If Full mode selected:

• Use Glob: docs/plans/*.md (excludes completed/)
• Plan is REQUIRED
• IMPORTANT: Glob returns oldest-first, so REVERSE the list to get most recent first
• Build AskUserQuestion with up to 4 most recent plans
• First option (most recent) should have "(Recommended)" suffix
• User MUST select one

If Review or Codex-only mode selected:

• Use Glob: docs/plans/**/*.md (includes completed/ for context)
• Plan is OPTIONAL
• IMPORTANT: Glob returns oldest-first, so REVERSE the list to get most recent first
• Build AskUserQuestion with up to 4 most recent plans PLUS "None" option at the end
• First plan option (most recent) should have "(Recommended)" suffix
• "None" option description: "Review existing changes without a plan file"
• If user selects "None", run without plan file

Step 4: Ask Max Iterations

Use AskUserQuestion:

• header: "Iterations"
• question: "Maximum number of task iterations?"
• options:
• label: "50 (Recommended)"

description: "Default - suitable for most plans"

• label: "25"

description: "Shorter plans or quick iterations"

• label: "100"

description: "Large plans with many tasks"

Step 5: Launch ralphex in Background

Build and run the command:

bash
ralphex \
  [--review]              # if user selected "Review" mode
  [--codex-only]          # if user selected "Codex-only" mode
  [--max-iterations N]    # from user selection (25, 50, or 100)
  [plan-file]             # from argument OR plan selection (omit if "None" selected)

Run using Bash tool with run_in_background: true. Save the task_id from the response - needed for status checks later.

Determine progress filename based on mode and plan selection:

• Full mode + plan: .ralphex/progress/progress-{plan-stem}.txt
• Review mode + plan: .ralphex/progress/progress-{plan-stem}-review.txt
• Codex-only + plan: .ralphex/progress/progress-{plan-stem}-codex.txt
• Full mode + no plan: .ralphex/progress/progress.txt
• Review mode + no plan: .ralphex/progress/progress-review.txt
• Codex-only + no plan: .ralphex/progress/progress-codex.txt

Where {plan-stem} is the plan filename without extension (e.g., fix-bugs from fix-bugs.md).

Step 6: Confirm Launch

1. Wait 10-15 seconds for initialization
2. Read last 20 lines of progress file: tail -20 [progress-filename]
3. Confirm ralphex started by checking for "Plan:", "Branch:", "Started:" lines
4. Report launch confirmation:

ralphex started. Task ID: [task_id]

Plan: [plan file from progress file]
Branch: [branch from progress file]
Mode: [mode from progress file]
Progress file: [progress-filename]

Manual monitoring:
  tail -f [progress-filename]      # live stream
  tail -50 [progress-filename]     # recent activity

ralphex runs autonomously (can take hours). Process continues if you close this conversation.
Ask "check ralphex" to get status update.

STOP HERE after reporting launch status. Do not continue monitoring automatically.

Step 7: Progress Check (only on explicit user request)

If user explicitly asks "check ralphex", "ralphex status", or "how is ralphex doing":

1. Use TaskOutput tool with block: false to check process status (use task_id from Step 5)
2. Read last 40 lines of progress file (use filename from Step 5)

If process still running:

• Report current phase from progress file:
• "task iteration N" → Task Execution phase
• "codex iteration N" → Codex External Review phase
• "review pass 1/2" → Claude Review phase
• Show recent activity lines

If process exited (TaskOutput shows completion):

• Exit code 0 → success, report "ralphex completed successfully"
• Exit code non-zero → failure, report "ralphex failed"
• Read final lines of progress file for summary

After reporting status, STOP. Do not offer to do anything else.

Constraints

• This command is ONLY for launching and monitoring ralphex
• Do NOT offer to help with code, commits, PRs, or anything else
• Do NOT make suggestions or recommendations beyond status reporting
• Do NOT take any actions on the codebase
• After launch confirmation: wait for user to explicitly request status check
• After status check: report and stop

Nested Claude Code Sessions

ralphex automatically strips the CLAUDECODE env var from child processes, allowing it to run from inside Claude Code. If the nested session error is somehow encountered, ralphex detects it via error pattern matching and exits gracefully instead of looping.

Running from a standalone terminal is still recommended for the best experience.