| name | super-ralph-wiggum |
| description | 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.
The 11 Tips (Quick Reference)
Based on AI Hero's definitive guide:
| # | Tip | Key Insight |
|---|
| 1 | Ralph Is A Loop | Same prompt, multiple iterations |
| 2 | Start HITL, Then AFK | Learn → Trust → Let go |
| 3 | Define The Scope | Explicit stop conditions prevent infinite loops |
| 4 | Track Progress | progress.txt bridges context windows |
| 5 | Use Feedback Loops | Types, tests, linting as guardrails |
| 6 | Take Small Steps | One logical change per commit |
| 7 | Prioritize Risky Tasks | Architecture first, quick wins last |
| 8 | Define Software Quality | Tell Ralph what kind of repo this is |
| 9 | Use Docker Sandboxes | Essential for AFK safety |
| 10 | Pay To Play | HITL still valuable without AFK |
| 11 | Make It Your Own | Alternative loop types, task sources |
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:
./scripts/setup-ralph-loop.sh --template test-coverage --docker > run-ralph.sh
chmod +x run-ralph.sh
./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@references/browser-testing.md - Dev-browser integration
Template Details
test-coverage
Improves test coverage by:
- Running coverage to find gaps
- Identifying most important untested user-facing behavior
- Writing ONE meaningful test per iteration
- Using
/* v8 ignore */ for non-essential code
- Committing after each successful test
Read full template: @templates/test-coverage.md
feature-prd
Implements features from a PRD file by:
- Reading
prd.json for highest-priority incomplete feature
- Checking dependencies are satisfied
- Implementing ONE feature per iteration
- Running verification (typecheck + tests)
- Updating AGENTS.md with patterns discovered
- Marking feature as
passes: true
Read full template: @templates/feature-prd.md
lint-fix
Fixes lint errors by:
- Running linter to get error list
- Picking file with most errors
- Fixing ALL errors in that file
- Verifying fixes don't break tests
- Committing and moving to next file
Read full template: @templates/lint-fix.md
entropy-loop
Reverses software entropy by:
- Scanning for code smells (unused exports, dead code, TODOs)
- Fixing ONE issue per iteration
- Running verification
- Documenting changes in progress.txt
Read full template: @templates/entropy-loop.md
duplication-loop
Eliminates duplicate code by:
- Running jscpd to find duplicates
- Identifying ONE duplication group
- Extracting shared code into utility/helper
- Updating all call sites
- Verifying with tests
Read full template: @templates/duplication-loop.md
docs-generation
Generates documentation by:
- Identifying undocumented public functions
- Writing ONE doc per iteration
- Verifying examples compile/run
- Including JSDoc and README updates
Read full template: @templates/docs-generation.md
dataset-generation
Generates training data by:
- Creating samples meeting quality criteria
- Validating quality per iteration
- Tracking count in progress.txt
- Stopping at target count
Read full template: @templates/dataset-generation.md
migration
Migrates codebase by:
- Reading migration plan from file
- Migrating ONE module per iteration
- Ensuring tests pass after each
- Tracking migrated vs remaining
Read full template: @templates/migration.md
Canceling a Loop
To stop an active Ralph loop, delete the state file:
rm .claude/ralph-loop.local.md
Or wait for max iterations to be reached.
Attribution
Based on the Ralph Wiggum technique by Geoffrey Huntley.
Enhanced with learnings from Ryan Carson, Matt Pocock, and AI Hero.
