Ralph Wiggum is the viral agentic coding loop.Simplified for real-world teams.
Open source, spec-driven, and community-led. Ralph Wiggum turns AI agents into reliable builders with clear specifications, autonomous loops, and deployment-ready results.
AI coding agents are powerful.But they need structure.
Modern AI agents can write entire applications. Without clear specifications, they wander, over-engineer, and lose focus on what actually matters.
Ralph Wiggum + SpecKitThe best of both worlds.
We combine the Ralph loop with a lighter SpecKit workflow, so AI agents get clear acceptance criteria without the overhead.
How it works
Two modes. One loop. Fresh context.
Based on Geoffrey Huntley's original methodology.
Run planning mode. The AI compares specs vs code, creates a prioritized task list in IMPLEMENTATION_PLAN.md.
./scripts/ralph-loop.sh plan
Run build mode. Each iteration picks ONE task from the plan, implements it, tests, commits, then exits for fresh context.
./scripts/ralph-loop.sh
The loop restarts with fresh context. The AI reads the updated plan, picks the next task. Eventually, everything is done.
<promise>DONE</promise>
Why Ralph Wiggum
Core principles from Geoffrey Huntley.
Fresh context each loop
Each iteration spawns a new agent process with a clean context window. The agent reads specs from disk, picks one task, implements it, and exits.
No context compaction
Unlike exit-hook plugins that force the same session to continue until done (causing context overflow and lossy compaction), our approachterminates and restarts cleanly between tasks.
Backpressure via tests
Tests, builds, and lints reject invalid work. The agent must fix issues before committing. Natural convergence through iteration.
Let Ralph Ralph
Trust the AI to self-identify, self-correct, and self-improve. Don't micromanage. Observe patterns and adjust prompts.
Why fresh context matters
Some agentic approaches use exit hooks that hijack the session and force the agent to continue indefinitely until acceptance criteria are met. This leads to:
- ✗Context window overflows after many retries
- ✗Forced compaction loses important context → quality degradation
- ✗Agent gets confused by its own old, stale reasoning
Our approach: The bash loop picks a spec, runs a fresh agent instance, checks if <promise>DONE</promise> was output. If yes → move to next spec. If no → retry the same spec, but with a completely fresh context window. No compaction, no degradation.
Open source community
Built in public, for the public.
Ralph Wiggum lives on GitHub, shaped by the open source community and shared with a non-profit spirit. Fork it, remix it, and ship better specs with the world.
Transparent, forkable, and built to empower contributors.
Ideas evolve in the open and stay friendly to every builder.
Share it freely, use it commercially, and keep it moving.
FAQ
Quick answers for builders.
What is Ralph Wiggum?
Ralph Wiggum is a viral agentic coding loop that combines spec-driven development with autonomous iteration so AI agents ship reliable results.
How do I start?
Point your AI agent to the GitHub repo. It will set up the files. Then run ./scripts/ralph-loop.sh plan to create the task list, and ./scripts/ralph-loop.sh to start building.
Does it work with my AI agent?
Yes. Ralph Wiggum works with Claude Code, OpenAI Codex, Cursor, and any agent that can follow the prompts.
The elegance is in the simplicity
There's no complex orchestration. Just a bash loop that keeps restarting the AI agent. The agent figures out what to do next by reading the plan file each time. The plan file on disk is the shared state.
while :; do cat PROMPT.md | claude -p ; done Loop 1: Read plan → Pick task A → Implement → Test → Commit → Exit Loop 2: Read plan → Pick task B → Implement → Test → Commit → Exit Loop 3: Read plan → Pick task C → Implement → Test → Commit → Exit ...
Getting started
Start building in 60 seconds.
Paste either prompt into your AI agent and you are ready to go.
New project
Use this when starting from scratch.
Existing project
Use this to add Ralph Wiggum to an existing repo.
Why we recommend SpecKit
We recommend SpecKit by GitHub because it provides a systematic, professional way to collect specifications. This aligns perfectly with Geoffrey Huntley's vision where planning is a crucial step — clear specs with testable acceptance criteria are essential for the Ralph loop to know when work is truly complete.
That said, you can use any tracking system (GitHub Issues, Jira, Linear, plain markdown) as long as each work item has clear acceptance criteria.
Here's how we adapted SpecKit for the Ralph workflow:
| SpecKit Step | Our Approach | Why |
|---|---|---|
| /speckit.constitution | Keep ✓ | Essential project principles |
| /speckit.specify | Keep ✓ (enhanced) | Specs with clear acceptance criteria |
| /speckit.plan | Optional | AI agents can plan dynamically |
| /speckit.tasks | Optional | AI agents break down work automatically |
| /speckit.implement | Replace with Ralph loop | Iterative until acceptance criteria pass |
Standing on the shoulders of giants
Ralph Wiggum builds on the work of incredible people and teams. We are sharing our interpretation of Geoffrey Huntley's original idea, influenced by Matt Pocock's variant, and refined to feel more approachable for modern agentic coding.