Run Claude Code in autonomous iteration loops until task completion — PRD-based feature development, test coverage improvement, lint fixing, documentation generation, dataset creation, or framework migrations. Uses in-session loop mechanism with specialized templates. Triggers on autonomous loop, iterate until done, run until passing, keep going until, ralph, PRD execution.
Run Claude Code in autonomous iteration loops until task completion — PRD-based feature development, test coverage improvement, lint fixing, documentation generation, dataset creation, or framework migrations. Uses in-session loop mechanism with specialized templates. Triggers on autonomous loop, iterate until done, run until passing, keep going until, ralph, PRD execution.
Super Ralph Wiggum
Autonomous iteration loops for Claude Code. Run the same prompt repeatedly until task completion, with context persisting through files and git history.
The Ralph Philosophy
The agent chooses the task, not you.
You define the end state. Ralph figures out how to get there.
With multi-phase plans, a human writes a new prompt at the start of each phase. With Ralph, the agent picks what to work on next from your PRD. You describe the destination. Ralph navigates.
See @references/tips-and-tricks.md for detailed guidance on each tip.
Quick Start
To start a Ralph loop with a template:
Run the super-ralph-wiggum skill with the test-coverage template, max 20 iterations
To start with a PRD file:
Run super-ralph-wiggum with feature-prd template using ./prd.json
Available Templates
Template
Use Case
Default Iterations
test-coverage
Improve test coverage to target %
30
feature-prd
Implement features from PRD file
20
lint-fix
Fix all lint errors incrementally
30
docs-generation
Generate documentation for modules
25
dataset-generation
Generate training data samples
50
migration
Migrate to new framework/version
40
entropy-loop
Reverse software entropy (dead code, smells)
30
duplication-loop
Eliminate duplicate code
25
Invocation Patterns
Template Mode (Recommended)
Use a pre-built template for common tasks:
Use super-ralph-wiggum with [template-name] template
Options: --max-iterations N, --browser (for UI verification)
PRD Mode
For structured feature development with task tracking:
Use super-ralph-wiggum with feature-prd template
PRD file: ./prd.json
The PRD file tracks features with passes: true/false. Loop completes when all features pass.
HITL Mode (Single Iteration)
For interactive learning and pair programming:
Use super-ralph-wiggum with --once flag to [task description]
Runs ONE iteration without looping. Great for learning how Ralph works.
Custom Prompt
For tasks not covered by templates:
Use super-ralph-wiggum with custom prompt:
[Your detailed task description with completion criteria]
Completion: Output <promise>COMPLETE</promise> when done
Max iterations: 15
The Two Modes: HITL vs AFK
Mode
How It Works
Best For
HITL (human-in-the-loop)
Run once, watch, intervene
Learning, prompt refinement, risky tasks
AFK (away from keyboard)
Run in a loop with max iterations
Bulk work, low-risk tasks, overnight runs
The progression is simple:
Start with HITL to learn and refine
Go AFK once you trust your prompt
Review the commits when you return
For AFK, always cap iterations:
Small tasks: 5-10 iterations
Medium tasks: 15-30 iterations
Large features: 30-50 iterations
Explicitly Define Software Quality
Ralph doesn't know if this is a throwaway prototype or production code. Tell it.
Repo Type
What To Say
Expected Behavior
Prototype
"Speed over perfection. Skip edge cases."
Takes shortcuts
Production
"Must be maintainable. Follow best practices."
Adds tests, docs
Library
"Public API. Backward compatibility matters."
Careful about breaking changes
Code Quality Prompt
If the loop should maintain high code quality, specify it factually:
Maintain existing code conventions and quality standards.
Each change should leave test coverage equal to or better than before.
Prefer incremental improvements over large rewrites.
Avoid motivational framing ("fight entropy", "be thorough")—Claude 4.6 already tends toward thoroughness and these amplify it into over-planning. Factual quality criteria are more effective.
The Repo Wins
Your instructions compete with your codebase. When Ralph explores your repo, it sees two sources of truth: what you told it to do and what you actually did.
If you write "never use any types" but Ralph sees any throughout your existing code, it will follow the codebase, not your instructions.
Claude learns patterns from the existing codebase. If the codebase uses any types throughout, the loop will follow that pattern regardless of instructions. Clean up the specific patterns you care about before running the loop.
Task Prioritization Order
When choosing the next task, Ralph should prioritize:
Architectural decisions and core abstractions
Integration points between modules
Unknown unknowns and spike work
Standard features and implementation
Polish, cleanup, and quick wins
Fail fast on risky work. Save easy wins for later.
Use HITL Ralph for early architectural decisions—the code from these tasks stays forever. Save AFK Ralph for when the foundation is solid.
Execution Modes
1. In-Session Mode (Default)
Loop runs inside your current Claude Code session using stop hooks:
Use super-ralph-wiggum with test-coverage template, max 20 iterations
Stop hook intercepts exit attempts
Same prompt fed back each iteration
Context persists through files and git
Best for interactive/monitored work
2. Dockerized Mode (External)
Loop runs externally via bash script with Docker sandbox:
# Generate external script
./scripts/setup-ralph-loop.sh --template test-coverage --docker > run-ralph.sh
chmod +x run-ralph.sh
# Run in background
./run-ralph.sh 20 &
Each iteration is a fresh Claude Code instance
Docker isolation for safety
Best for overnight/AFK runs
Memory persists only via files
Essential for AFK safety: Docker sandboxes let Ralph edit project files and commit—but can't touch your home directory, SSH keys, or system files.
How It Works
Setup: Creates state file at .claude/ralph-loop.local.md
Progress: Auto-creates progress.txt in project root
Loop: Stop hook intercepts exit, feeds same prompt back
Completion: Detects <promise>COMPLETE</promise> or PRD all-pass
Learning: Patterns accumulate in progress.txt across iterations
Key Options
Option
Description
Default
--template <name>
Use pre-built template
(required or custom prompt)
--prd <file>
PRD file for task tracking
none
--max-iterations <n>
Iteration limit
varies by template
--completion-promise <text>
Custom completion phrase
COMPLETE
--progress <file>
Progress file location
./progress.txt
--browser
Enable browser testing prompts
false
--once
Single iteration (HITL mode)
false
Best Practices
1. Small Stories
Tasks must fit in one context window. Break large features into atomic stories.
2. Verification First
Always run typecheck + tests before committing. Templates enforce this.
3. Cap Iterations
For AFK (unattended) Ralph, always set --max-iterations. Infinite loops are dangerous with stochastic systems.
4. Clear Completion Criteria
Vague tasks risk infinite loops. Be explicit about when to stop.
5. Use Progress File
Previous iteration learnings persist in progress.txt. Templates auto-inject this.
6. One Change Per Commit
Keep changes small and focused. Prefer multiple small commits over one large commit.
7. Structure State Appropriately
Use JSON for structured progress data (coverage percentages, feature pass/fail, migration counts). Use freeform text in progress.txt for observations and session learnings. Use git commits as checkpoints between iterations so each new context window can discover state from the filesystem.
References
For detailed guidance, read the reference files:
@references/tips-and-tricks.md - The 11 Tips expanded with AI Hero insights
@references/prompt-patterns.md - 10 patterns for convergent prompts
@references/prd-schema.md - PRD file structure and usage
@references/cost-estimation.md - API cost guidelines
