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:
FileContents
.statusCurrent iteration out of max (e.g. `310`)
.phasesPhase-by-phase progress with timestamps
.tokensToken usage: input, output, cache create, cache read
.logFull execution log from the coding agent
.finalFinal outcome after completion
The TUI RunScreen reads these files to display live progress.

​
Worktree isolation

Use --worktree to run the loop in an isolated git worktree: 
wiggum run my-feature --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: 
wiggum run my-feature --resume
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: 
# Set implementation agent
wiggum config set cli claude     # or: codex

# Set review agent (can differ from implementation)
wiggum config set review-cli claude  # or: codex
Or override per-run: 
wiggum run my-feature --cli codex --review-cli claude

​
Loop configuration

Fine-tune loop behavior in ralph.config.cjs: 
loop: {
  maxIterations: 10,              // max implementation iterations
  maxE2eAttempts: 5,              // max E2E test retries
  defaultModel: 'sonnet',         // model for implementation
  planningModel: 'opus',          // model for planning phase
  codingCli: 'claude',            // agent for implementation
  reviewCli: 'claude',            // agent for review phase
  reviewMode: 'auto',             // manual | auto | merge

  // Claude Code settings
  claudePermissionMode: 'acceptEdits',

  // Codex CLI settings
  codexModel: 'gpt-5.3-codex',
  codexSandbox: 'workspace-write',
  codexApprovalPolicy: 'on-failure',
}
See configuration for full details on each option.

​
Ralph loop vs bash scripts

AspectBash scriptRalph loop (Wiggum)
ExecutionSingle undifferentiated retry loop5 isolated phases with checkpoints
Spec qualityManual promptAI-generated from codebase context
Error recoveryRestart from scratchPhase-level retry
MonitoringTerminal outputTUI with phase tracking and token usage
Agent supportHardcoded to one agentAny CLI agent (Claude, Codex, Gemini, etc.)
ResumeNot supportedCheckpoint-based resume