Fresh context each iteration. Memory lives in git, docs, and task files—not in the conversation.
Source: Vinci Rufus | Origin: Geoffrey Huntley | Date: 2025 | Roman Kuhn – Video Explainer
Core Concept
The RALPH Loop is a bash script pattern that runs an AI coding agent repeatedly until all tasks are complete, spawning fresh agent instances each iteration. This addresses a fundamental LLM limitation: context degradation in lengthy conversations.
“As conversations extend, attention becomes diluted, leading to degraded performance, hallucinations, and poor decision-making.”
The Simplest Mental Model: Two Loops
Strip away everything and the RALPH Loop is just an outer loop wrapping an inner loop.
Inner loop (Claude Code / any agentic harness): runs automatically.
User message -> Claude -> tool call -> result -> Claude -> tool call -> ... -> response
This is the agentic while-loop. Claude decides what tools to call, executes them, feeds results back, and repeats until the task is done. Claude Code itself is ~200 lines of code: a system prompt, 4 tools (bash, read, edit, write), and a while loop.
Outer loop (the RALPH loop): you restart it.
Task 1 -> inner loop completes -> done
Task 2 -> inner loop completes -> done
Task 3 -> inner loop completes -> done
...until the task queue is empty
The outer loop is not tool calls inside tool calls. It pulls the next task from a list, hands it to a fresh agent instance, waits for completion, then pulls the next task. It is a task queue with an LLM agent as the worker.
The key difference from just “using Claude Code” is that you never stop. You keep feeding it the next task, or you automate that feeding. Instead of you thinking “what should I build next?”, the loop decides.
Huntley describes it as “a mindset that these computers can be indeed programmed.” It is less about the code and more about the shift: stop writing code line by line, start programming the loop that writes the code.
The Iteration Pattern
┌─────────────────────────────────────────────────────────────┐
│ 1. Select highest-priority incomplete task │
│ 2. Implement the single task │
│ 3. Run quality checks (type-checking, tests) │
│ 4. Commit if checks pass │
│ 5. Update task status │
│ 6. Document learnings │
│ 7. SPAWN NEW AGENT INSTANCE → Repeat │
└─────────────────────────────────────────────────────────────┘
Critical innovation: Each iteration starts with a clean context window. Memory persists only through:
- Git history
- Progress/task files
- AGENTS.md / CLAUDE.md documentation
The Four-Phase Cycle
| Phase | Effort | Focus |
|---|---|---|
| Plan | ~40% | Research approaches, analyze codebase, synthesize strategy |
| Work | ~20% | Write code and tests per established plan |
| Review | ~40% | Examine outputs, extract lessons |
| Compound | Critical | Document patterns, gotchas, conventions for future iterations |
The Compound phase is what turns individual iterations into accumulated advantage.
The Compound Phase: Four Dimensions
Source: Agentic Patterns
Document findings across four dimensions after each feature:
| Dimension | Questions to Answer |
|---|---|
| Plan effectiveness | What succeeded? What required adjustment? |
| Testing discoveries | What issues were missed during development? |
| Common errors | What patterns of agent mistakes emerged? |
| Reusable patterns | What best practices are worth formalizing? |
Embed learnings into:
- System prompts (CLAUDE.md)
- Slash commands
- Specialized subagents
- Automated hooks
- Test suites
“Each feature becomes curriculum for the next.”
Trade-offs:
- Benefits: Accelerated productivity, knowledge preservation, improved onboarding, reduced repetition
- Costs: Discipline demands, maintenance requirements, prompt complexity growth
Why Fresh Context Matters
LLMs experience “context rot”:
- Attention dilutes over long conversations
- Decisions degrade
- Hallucinations increase
- Performance drops
The RALPH Loop sidesteps this by treating each iteration as autonomous.
This mirrors effective human developer practices:
- Focused, discrete sessions
- Not marathon coding where fatigue compounds errors
- Unlike humans, AI can cycle through infinite fresh contexts without fatigue
AGENTS.md: Knowledge Accumulation
Repository-based files (AGENTS.md or CLAUDE.md) store codebase-specific knowledge:
- Conventions
- Patterns
- Gotchas
- Best practices
After each loop iteration, agents update these files with learnings.
The flywheel effect:
Development → Documented Knowledge → Faster Future Work → More Development
Since AI coding tools automatically read these files, future iterations benefit immediately from previously discovered insights.
Essential Feedback Loops
The RALPH Loop requires robust verification mechanisms:
| Mechanism | Purpose |
|---|---|
| Type-checking | Prevents type errors from propagating |
| Automated tests | Verify specifications, prevent regression |
| Continuous integration | Maintains deployable codebase state |
| Browser verification | Confirms frontend changes (Playwright) |
Without feedback loops, the RALPH Loop becomes a chaos engine—rapidly producing broken code. With them, it becomes production-quality automation.
Task Sizing Discipline
Success requires breaking work into single-context-window units.
Well-sized tasks:
- Database migration
- Single UI component
- Server action update
- API endpoint implementation
Oversized tasks (need decomposition):
- “Build entire dashboard”
- “Implement auth system”
- “Refactor the codebase”
“Each task should have a clear definition of done and verifiable acceptance criteria.”
The Economic Shift
The RALPH Loop shifts software economics:
| Old Model | New Model |
|---|---|
| Expensive human typing | Cheap AI inference cycles |
| Engineer writes code | Engineer orchestrates systems |
| Code production | Architecture + feedback loops + quality gates |
This distinguishes software development (code production) from software engineering (system design).
Gas Town: The Multi-Agent Future
The logical extension: multiple agents working simultaneously on granularly-decomposed tasks.
┌─────────────────────────────────────────────────────────────┐
│ Human Engineer │
│ (Architecture + Strategy) │
└─────────────────────┬───────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Agent 1 │ │ Agent 2 │ │ Agent 3 │
│ Task A │ │ Task B │ │ Task C │
└─────────┘ └─────────┘ └─────────┘
│ │ │
└─────────────┴─────────────┘
│
Git + AGENTS.md
(Shared Memory)
Steve Yegge calls this “Gas Town”, fleets of agents in fresh contexts, with human engineers focusing on architecture and strategy.
Huntley is developing “The Weaving Loom”, infrastructure for evolutionary software that runs continuously and autonomously optimizes for revenue generation. This is the logical endpoint: the loop never stops, and the human’s role shifts entirely to steering intent and defining constraints.
The Three-File Structure
Source: Roman Kuhn – Ralph Loop Explained
The Ralph loop relies on three files created during the planning phase:
| File | Purpose |
|---|---|
| spec.md | Full specification of what you’re building. Created through bidirectional prompting with the LLM. |
| implementation.md | Ordered task list with checkboxes. Each bullet = one task. Agent checks off tasks as they complete. |
| prompt.md | The exact prompt given to the agent at every iteration. Tells it to study the spec, pick the highest-priority unchecked task, implement it, write a unit test, and mark completion. |
Bidirectional Prompting (Creating spec.md)
You and the LLM ask each other questions until you’re both on the same page. The reason you ask the LLM questions back is that it reveals implicit assumptions the model made that seem obvious to you. These assumptions are typically the root of many bugs and become insidious as the repository grows.
You must read every single line of both spec.md and implementation.md and sign off on every line. If you skip this, you won’t understand the plan and implementation will diverge from your expectations. Errors cascade and amplify in Ralph loops because each iteration builds on the previous one.
Example prompt.md
1. Study spec.md thoroughly
2. Study implementation.md thoroughly
3. Pick the highest-leverage unchecked task
4. Complete the task
5. Write an unbiased unit test to verify
6. Include context about repository structure, conventions, etc.
Each loop starts with a fresh context window, so prompt.md must efficiently bring the agent up to speed.
The Dumb Zone: Why Fresh Context Works
Source: Roman Kuhn
The “dumb zone” is around 100k tokens used in context (for Opus-class models) where performance starts to rapidly drop. The Ralph loop’s core trick: instead of implementing more features in the same context window, update the spec and mark the subtask as complete. The implementation plan and spec become the source of truth, not previous context.
In vibe coding, compaction occurs at the context limit. Summarization tokens from previous implementation poison the model with irrelevant or contradictory information because they’re overcompacted. Most vibe coding implementation happens in the dumb zone, leaving gains on the table.
Ralph Loop: [spec+task] ──────────── stays below dumb zone per iteration
Vibe Coding: [growing context] ─────► hits limit ─► compaction ─► dumb zone
Three Usage Modes
Source: Roman Kuhn
1. Standard Implementation
The default mode. Spec thoroughly, watch the first few iterations intently. If Ralph goes off track, stop it, edit the spec, restart. This teaches you model behavior and gets you a more bulletproof spec. Once it looks on track, leave it running.
2. Exploration Mode
Nearly no downsides. For back-burner items: research tasks, questions, MVPs, feature spikes. Spend 5 minutes brain-dumping into Claude, have it write tasks and specs without overthinking them, launch the loop, walk away or go to sleep. Ideal for when your max plan usage resets the next day. Unused tokens have no downside.
3. Brute Force Testing
Use Ralph to systematically work through attack vectors (security) or every user-facing action (UI). Give Claude browser access (Playwright) for end-to-end tests. The loop works through each case overnight in a brute force manner, finding bugs and edge cases in a sandboxed environment.
Downsides
- Not token efficient. Parallel Ralph loops cause exponential token use.
- Quality trade-off. Reduced attention means separation from the actual implementation.
- Spec size risk. If spec is too big, context rot and compaction happen during implementation in every single loop, almost ensuring catastrophic failure. Keep spec and implementation plan as brief as possible.
- Bug propagation. A bad test or introduced bug poisons future loops and can completely derail the application.
- Specification difficulty. Expecting to know all changes upfront through conversation alone is extremely difficult. If you don’t know exactly what you want, use parallel sub-agents for exploration first, discard the code, take notes, then spec.
Do not use the Ralph Wigum plugin from Anthropic. It runs the loop within the same session, causing heavy context rot and compaction. The whole point is fresh context per iteration.
Implementation: Minimal RALPH Script
#!/bin/bash
# ralph.sh - Run agent loop until all tasks complete
while true; do
# Check for incomplete tasks
TASK=$(cat tasks.md | grep "- \[ \]" | head -1)
if [ -z "$TASK" ]; then
echo "All tasks complete"
exit 0
fi
# Fresh agent instance per task
claude --print "
Read AGENTS.md for context.
Read tasks.md and work on the first incomplete task.
Run tests after implementation.
If tests pass, mark task complete in tasks.md.
Update AGENTS.md with any learnings.
"
# Loop continues with fresh context
done
Current Reality
Companies like Every already practice compound engineering at scale:
- Single developers maintaining multiple products
- Estimated to perform work of 5 developers from years prior
- Not theoretical—production-stage development happening now
Key Insight
The RALPH Loop treats context degradation as a feature, not a bug. By forcing fresh starts, it ensures each iteration has maximum cognitive clarity.
Related
- Reverse Ralph Loop – The inverse pattern: extract specs from existing products, then reimplementing clean-room
- Writing a Good CLAUDE.md – The knowledge accumulation layer
- Learning Loops – Encoding insights
- Agent Reliability Chasm – Why fresh context helps reliability
- 12 Factor Agents – Factor 10: Small, Focused Agents
- Building the Harness – The meta-engineering layer
- Agent Swarms – Parallel agent patterns
External References
- Geoffrey Huntley – The Loop (original source)
- Vinci Rufus – The Ralph Loop and Compound Engineering
- Anthropic – Effective Harnesses for Long-Running Agents
- Will Larson – Learning from Every’s Compound Engineering
- Agentic Patterns – Compounding Engineering Pattern
- Roman Kuhn – The Ralph Loop Explained from First Principles
- Thought Leaders – People to follow in this space
Part of the field guide
This is one of my field notes in AI Native Software Engineering, a plain-English guide to building software with AI agents. The terms behind it are defined in the AI Coding Dictionary.
