🌻 prg.sh

Ralph Wiggum Loop

Jan 18, 20263 min read

Named after The Simpsons character known for relentless optimism despite setbacks, the Ralph Wiggum Loop is an autonomous AI coding technique created by Geoffrey Huntley in mid-2025.

Core idea: feed the same prompt to an AI agent repeatedly until it completes the task. Progress accumulates in files and git history, not in the LLM’s context window.

while :; do cat PROMPT.md | claude-code ; done

Why It Works

LLMs are stateless. Filesystems aren’t.

Each iteration, the agent sees code from previous attempts. Failures get piped back as context, creating what Huntley calls a “contextual pressure cooker.” The model is forced to confront its own mess, eventually finding correct solutions to escape the loop.

The skill shifts from “directing Claude step by step” to “writing prompts that converge toward correct solutions.”

Claude Code Plugin

Anthropic formalized the technique as an official plugin. Uses Stop hooks to intercept exit attempts.

/ralph-loop "<prompt>" --max-iterations 50 --completion-promise "COMPLETE"

Parameters:

  • --max-iterations <n>: Safety cap (critical for cost control)
  • --completion-promise <text>: Signal phrase the agent outputs when done

The hook blocks exit if the promise isn’t found in output, then feeds the prompt back. Repeat until promise appears or iterations exhausted.

Prompt Writing Patterns

Clear completion criteria:

Build feature X.
 
When complete:
- All tests passing
- Documentation updated
- Output: <promise>COMPLETE</promise>

Phased goals:

Phase 1: Authentication (JWT, tests)
Phase 2: CRUD operations (endpoints, validation)
Phase 3: Documentation
 
Output <promise>COMPLETE</promise> when all phases done.

Self-correction:

Follow TDD:
1. Write failing tests
2. Implement
3. Run tests
4. If fail, debug and fix
5. Repeat until green
6. Output: <promise>COMPLETE</promise>

Context Engineering Philosophy

Huntley describes tuning Ralph “like a guitar.” Each failure reveals a problem domain. You add guardrails (signs telling Ralph “SLIDE DOWN, DON’T JUMP”) until the prompt reliably converges.

“Your job is now to sit on the loop, not in it.”

The pattern applies beyond coding to any task where iteration beats perfection and verification is automatic.

Limitations

  • Drift risk: Without structure, loops iterate on the wrong thing
  • Cost: Uncapped iterations burn through API credits fast
  • Ambiguous tasks: Garbage prompts produce infinite loops on garbage
  • Large codebases: Navigating legacy code needs human judgment

Best suited for greenfield projects with testable outputs and clear requirements.

Combining with Spec Kit

The killer combo: Spec Kit provides structure (what to build), Ralph provides persistence (keep trying until done). A Prompt.md bridges them by teaching Ralph how to consume spec artifacts and iterate through tasks.

Forks and Variants

The Weaving Loom

Huntley is building toward “evolutionary software.” Systems that identify bugs, study codebases, fix issues, deploy, and verify, all autonomously. January 2026 saw the first demonstration: a system auto-healed a production bug without human intervention.

Sources

Graph View

Backlinks