super-ralph-wiggum

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:

1. Start with HITL to learn and refine
2. Go AFK once you trust your prompt
3. 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:

1. Architectural decisions and core abstractions
2. Integration points between modules
3. Unknown unknowns and spike work
4. Standard features and implementation
5. 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

1. Setup: Creates state file at .claude/ralph-loop.local.md
2. Progress: Auto-creates progress.txt in project root
3. Loop: Stop hook intercepts exit, feeds same prompt back
4. Completion: Detects <promise>COMPLETE</promise> or PRD all-pass
5. 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 syste