> ## Documentation Index
> Fetch the complete documentation index at: https://wiggum.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The Ralph loop

> How wiggum's 5-phase autonomous coding loop works — planning, implementation, E2E testing, verification, and PR review.

The Ralph loop is a structured autonomous coding methodology [pioneered by Geoffrey Huntley](https://ghuntley.com/ralph/). 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`](/commands/run) command.

## The five phases

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
  </Step>
</Steps>

## 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:

| File      | Contents                                             |       |
| --------- | ---------------------------------------------------- | ----- |
| `.status` | Current iteration out of max (e.g. \`3               | 10\`) |
| `.phases` | Phase-by-phase progress with timestamps              |       |
| `.tokens` | Token usage: input, output, cache create, cache read |       |
| `.log`    | Full execution log from the coding agent             |       |
| `.final`  | Final outcome after completion                       |       |

The [TUI RunScreen](/using-wiggum/interactive-mode) reads these files to display live progress.

## Worktree isolation

Use `--worktree` to run the loop in an isolated git worktree:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
wiggum run my-feature --cli codex --review-cli claude
```

## Loop configuration

Fine-tune loop behavior in `ralph.config.cjs`:

```js theme={null}
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](/using-wiggum/configuration) for full details on each option.

## Ralph loop vs bash scripts

| Aspect         | Bash script                        | Ralph loop (Wiggum)                         |
| -------------- | ---------------------------------- | ------------------------------------------- |
| Execution      | Single undifferentiated retry loop | 5 isolated phases with checkpoints          |
| Spec quality   | Manual prompt                      | AI-generated from codebase context          |
| Error recovery | Restart from scratch               | Phase-level retry                           |
| Monitoring     | Terminal output                    | TUI with phase tracking and token usage     |
| Agent support  | Hardcoded to one agent             | Any CLI agent (Claude, Codex, Gemini, etc.) |
| Resume         | Not supported                      | Checkpoint-based resume                     |