Skip to main content
The Ralph loop is a structured autonomous coding methodology pioneered by Geoffrey Huntley. Instead of running a coding agent in a single undifferentiated pass, it breaks execution into five distinct phases — each with its own prompt, checkpoints, and error handling. Wiggum implements the Ralph loop as feature-loop.sh, orchestrated by the wiggum run command.

​
The five phases

1

Planning

The coding agent reads the spec at .ralph/specs/<feature>.md and the codebase context from init. It produces <feature>-implementation-plan.md — a step-by-step task checklist.The plan accounts for your project’s file structure, naming conventions, and existing patterns.
2

Implementation

The agent works through the implementation plan task by task. Each iteration:
  1. Reads the checklist and picks the next pending task
  2. Writes code, tests, and configuration changes
  3. Commits the work
  4. Loops until all tasks are complete
Maximum iterations is configurable (default: 10). Use --max-iterations to override.
3

E2E testing

The agent runs end-to-end tests against the implementation. If tests fail, it iterates — fixing either the code or the tests.Maximum attempts is configurable (default: 5). Use --max-e2e-attempts to override.
4

Verification

The agent re-reads the original spec and checks every requirement against the actual implementation. Did it add the endpoint? Does the error handling match? Are edge cases covered?This is not a rubber stamp. It’s an explicit confirmation step that catches subtle cases where code “works” but doesn’t match what was specified.
5

PR review

Behavior depends on the review mode:
  • manual — Creates a PR with a structured description and stops
  • auto — Auto-reviews the diff against the spec, then creates the PR
  • merge — Auto-reviews, creates the PR, and auto-merges when CI checks pass

​
Phase isolation

The key insight of the Ralph loop is phase isolation. Each phase runs independently with its own:
  • Prompt template — Stored in .ralph/prompts/ (e.g. PROMPT_feature.md.tmpl for planning, PROMPT_e2e.md.tmpl for testing)
  • Status tracking — Each phase logs started → success or failed to a status file
  • Error handling — A failure in E2E testing doesn’t require restarting implementation
  • Retry logic — Each phase can retry independently
This prevents the agent from thrashing — the most common failure mode in unstructured autonomous coding loops.

​
Status tracking

While the loop runs, wiggum tracks progress in real-time status files: The TUI RunScreen reads these files to display live progress.

​
Worktree isolation

Use --worktree to run the loop in an isolated git worktree:
This creates a separate working directory for the feature branch, so the loop doesn’t interfere with your current work. Essential when running multiple features in parallel.

​
Resume from checkpoint

If a loop gets interrupted (crash, network issue, restart), resume from the last checkpoint instead of starting over:
This skips completed phases and picks up where it left off.

​
Choosing your coding agent

The Ralph loop works with any CLI-based coding agent. Configure which agent runs each phase:
Or override per-run:

​
Loop configuration

Fine-tune loop behavior in ralph.config.cjs:
See configuration for full details on each option.

​
Ralph loop vs bash scripts