What is Ralph Wiggum?
The Ralph loop pattern, outer bash automation, spec-driven tasks, fresh context each iteration, and a model-emitted completion sentinel.
Ralph Wiggum (the coding pattern, named after the Simpsons character) is a community label for a style of autonomous agentic development: an outer loop (usually a shell script) repeatedly starts your AI coding agent with narrow instructions, lets it work one slice, then checks whether it may continue. The agent does not "run forever" inside one giant chat, each pass is a new invocation with a clean context window, while truth lives on disk (specs, plans, tests, git history).
The ralph-wiggum repo is a full packaging of that idea (extra scripts, planning mode, plugins). This workshop's Implementing Ralph loops page uses a smaller script and folder layout but keeps the same ideas: specs on disk, fresh claude -p per iteration, and a model-emitted completion sentinel such as <promise>DONE</promise> / <promise>ALL_DONE</promise>.
What problem it solves
- Context rot: Long single-thread sessions accumulate noise; Ralph resets the model each loop and forces it to re-read files that matter.
- Vague "done": Without a completion protocol, models declare victory too early. Ralph uses an explicit final-result signal, and strong practice ties it to green tests, builds, and e2e/MCP checks. The sentinel is orchestration metadata, not proof by itself.
- Unbounded autonomy: The loop can cap iterations, track retry counts per spec, and stop when work is stuck or finished.
The loop in plain language
Each iteration roughly follows:
Orient: Read project rules (this workshop uses a short RALPH.md; heavier setups use a full constitution and optional IMPLEMENTATION_PLAN.md) plus specs/.
Pick one task: Highest-priority incomplete spec or plan item, not the whole backlog at once.
Implement and verify: Code, then prove it: unit tests, build/typecheck, and e2e or browser checks (CLI or MCP such as Playwright) must pass before the iteration counts as done, otherwise the loop is just unverified churn.
Commit: Keep history aligned with completed units of work. This workshop's ralph-loop.sh tells the agent never to git push; a human reviews and publishes.
Signal completion: Only when criteria are fully satisfied, emit the done token as an exact standalone line in the final result (this workshop: <promise>DONE</promise> per finished spec, <promise>ALL_DONE</promise> when nothing is left). The outer loop ignores matching text from explanations and tool results; independent tests still determine whether the claim is trustworthy.
Optional plan steps or IMPLEMENTATION_PLAN.md appear in larger setups; the minimal workshop flow works directly from specs/.
How this relates to subagents
Subagents (see Subagents) are inside Claude Code: the main session delegates a subtask and merges a compact result. A Ralph loop is outside the product: a script re-spawns the agent (or CLI) per iteration. You can use both, subagents for in-session delegation and a Ralph script for overnight or multi-hour spec grinding, but they solve different orchestration layers.
Risks (read this once)
Ralph-style setups give the agent real repo and often real git powers. Treat them like CI with a brain: use branches, review diffs, isolated environments when experimenting, and assume you must undo bad commits. The upstream repo ships an explicit "use at your own risk" warning for good reason.