What Is the Ralph Loop? How Autonomous Coding Loops Work

The problem with unstructured AI coding

Give a coding agent a vague instruction like “add user authentication” and watch what happens. It starts writing code immediately — often in the wrong place, with the wrong patterns, missing edge cases, and no tests. You end up spending more time fixing the output than you would have writing it yourself.

The issue isn’t that AI agents are bad at coding. It’s that they’re bad at planning. METR’s 2025 research on AI agent capabilities shows that AI agent success rates drop sharply as task complexity increases — from near-100% on tasks a human finishes in under 4 minutes, to less than 10% on tasks requiring over 4 hours of human effort. Without structure, agents default to the most obvious implementation path, which is rarely the best one.

Enter the Ralph loop

The Ralph loop is an autonomous coding methodology pioneered by Geoffrey Huntley. Instead of letting an agent freestyle its way through a feature, the Ralph loop imposes a structured, multi-phase execution cycle:

1. Plan — The agent reads the spec and creates a detailed implementation plan
2. Implement — Code gets written according to the plan
3. Test — Automated tests are written and run
4. Verify — The agent checks its own work against the original spec
5. PR — A pull request is created with a summary of changes

Each phase has clear inputs and outputs. Each phase can be monitored, paused, or retried independently. The agent doesn’t just barrel through — it checkpoints at every stage.

Why phases matter

Consider what happens when implementation hits a wall. In an unstructured loop, the agent might thrash — rewriting the same code over and over, getting stuck in a cycle of failed attempts. With the Ralph loop, if implementation fails, you know exactly where it failed and can intervene at that specific phase.

The verification step is especially important. Most autonomous coding tools declare success when the code compiles and tests pass. The Ralph loop adds an explicit verification phase where the agent re-reads the original specification and confirms that every requirement was actually met. This catches the subtle cases where code “works” but doesn’t do what was asked. GitClear’s 2025 analysis of 211 million lines of code changes found that AI-assisted development correlates with copy-pasted code rising from 8.3% to 12.3% of all changes, while refactoring dropped from 25% to under 10% — patterns that indicate quick fixes rather than thoughtful design. Explicit verification catches these quality issues before they reach production.

How Wiggum implements the Ralph loop

Wiggum CLI is a concrete implementation of the Ralph loop technique. Here’s what each phase looks like in practice:

Planning phase

The agent receives your spec (generated by wiggum new) and produces a step-by-step implementation plan. This plan is visible in the TUI so you can review it before execution continues. The plan accounts for your project’s specific file structure, patterns, and conventions — because wiggum init captured all of that context.

Implementation phase

Code gets written according to the plan. The agent creates or modifies files, adds imports, updates configurations. Because it’s working from a structured plan (not a vague description), the changes tend to be more focused and consistent.

Testing phase

The agent writes tests for the new functionality and runs the existing test suite. If tests fail, it iterates — fixing either the implementation or the tests until everything passes.

Verification phase

The agent re-reads the original spec and checks each requirement against the actual implementation. Did it add the API endpoint? Does the error handling match the spec? Are the edge cases covered? This isn’t a rubber stamp — it’s an explicit confirmation step.

PR phase

Finally, the agent creates a pull request with a structured description: what was changed, why, and how to test it. The PR is ready for human review.

The Ralph loop vs. bash-script loops

If you search for “Ralph loop” today, you’ll find plenty of bash scripts that wrap Claude Code or Codex in a while true loop. They run the agent, check if it succeeded, and retry if it didn’t. These capture the spirit of autonomous execution but miss the structure that makes the Ralph loop effective.

The difference is phase isolation. A bash-script loop is a single undifferentiated blob — the agent does everything in one pass, and if something goes wrong, you restart from scratch. The Ralph loop separates concerns: planning happens before implementation, testing happens after implementation, verification happens after testing. Each phase can succeed or fail independently.

Wiggum implements this phase structure natively. Each phase runs as a distinct step with its own progress tracking, error handling, and retry logic. You can monitor individual phases in the TUI, background the process, and come back to review results.

When to use the Ralph loop

The Ralph loop works best for well-specified features. The better your spec, the better the output. This is why Wiggum pairs the Ralph loop with a spec generation step — the AI interview ensures your spec is detailed enough for autonomous execution.

Good candidates for the Ralph loop:

• CRUD features — well-defined inputs and outputs
• API endpoints — clear request/response contracts
• UI components — detailed design specs
• Refactoring tasks — mechanical changes with clear before/after
• Test coverage — writing tests for existing code

Less ideal candidates:

• Exploratory work — when you’re not sure what you want yet
• Deeply creative tasks — novel algorithms, architecture design
• Cross-cutting concerns — changes that touch every file in the project

Getting started

To use the Ralph loop via Wiggum:

wiggum init    # scan your codebase
wiggum new     # generate a spec through AI interview
wiggum run     # execute the Ralph loop

The loop runs autonomously with progress checkpoints. You can monitor it in the TUI, background it, and review the pull request when it’s done.

For more on the technique itself, read Geoffrey Huntley’s original writeup on the Ralph loop. To see how Wiggum implements it end-to-end, read What Is Wiggum CLI?