Skip to main content
Hands a feature spec to your coding agent and runs the full Ralph loop — five structured phases with independent checkpoints, error handling, and retry logic.

​
How it works

  1. Loads the spec from .ralph/specs/<feature>.md
  2. Combines it with project prompts, guides, and context from .ralph/
  3. Spawns feature-loop.sh which orchestrates the coding agent through five phases:
Each phase can succeed or fail independently. A failure in E2E testing doesn’t require restarting implementation.

​
Flags

​
string
required
Name of the feature spec to run. Must match a file in .ralph/specs/.
​
string
Coding agent for implementation. Options: claude, codex. Overrides the default set in ralph.config.cjs.
​
string
Coding agent for the review phase. Can differ from the implementation agent.
​
boolean
default:"false"
Run in a git worktree for isolation. Creates a separate working directory so the loop doesn’t interfere with your current work. Recommended for parallel feature development.
​
boolean
default:"false"
Resume from the last checkpoint if a previous run was interrupted. Skips completed phases.
​
string
default:"manual"
What happens after the loop completes:
  • manual — Creates a PR and stops for human review
  • auto — Auto-reviews the diff against the spec, then creates the PR
  • merge — Auto-reviews, creates PR, and auto-merges when CI checks pass
​
string
AI model for the coding agent. Options depend on your provider (e.g., opus, sonnet for Anthropic).
​
number
default:"10"
Maximum number of implementation iterations. Each iteration picks the next task from the plan, writes code, and commits.
​
number
default:"5"
Maximum number of E2E test retries.

​
TUI monitoring

When run in an interactive terminal, wiggum shows a live RunScreen with:
  • Phase progress — Each phase shows status (pending, active, completed, failed) with duration
  • Iteration counter — Current iteration out of max (e.g. 3/10)
  • Activity feed — Real-time stream of what the coding agent is doing
  • Token tracking — Input/output token counts and cache metrics
  • Task checklist — Implementation plan tasks with completion status

​
Background mode

Press Esc to background the loop and return to the wiggum shell. The loop continues running. Re-attach with:

​
Completion summary

When the loop finishes, the RunScreen shows:
  • Phase durations
  • Final iteration count
  • File changes summary
  • Commit history
  • PR link (if created)

​
Examples