ralph-wiggum · git:20261026.7a89c23 · 2026-10-26 · sha256 7d0f4c95260644ea
ralph-wiggum git:20261026.7a89c23B
Immutable. This exact content never changes and is served at /api/v1/blob/7d0f4c95260644ea.
--- name: ralph-wiggum description: Autonomous AI coding loop for unattended development - lets Claude work continuously on tasks while you sleep, with mandatory sandbox enforcement for safety allowed-tools: - Bash - Read - Write - Edit - Glob - Grep - Task - TodoWrite --- # Ralph Wiggum Mode "Me fail English? That's unpossible!" - Ralph Wiggum Ralph Wiggum Mode is an autonomous AI coding loop that enables Claude Code to work continuously on tasks without human intervention. Named after the persistently optimistic Simpsons character, this technique lets Claude work "overnight shifts" while you sleep. ## Key Principle **Progress persists in files and git, not in the LLM's context window.** When context fills up, the loop restarts Claude with fresh context. The new instance picks up from the filesystem state (your code, git history, and task tracking files). ## When to Use This Skill Use Ralph Wiggum mode for: - Overnight feature development - Bug bashes (fixing multiple issues) - Test coverage improvement - Refactoring large codebases - Documentation generation - Any multi-step task you'd like completed while away ## Security Model **CRITICAL: Ralph requires a sandboxed environment.** Ralph uses `--dangerously-skip-permissions` which can: - Delete files without confirmation - Read credentials (~/.ssh, ~/.aws) - Make network requests - Run arbitrary commands **Ralph will REFUSE to start unless it detects:** - Container environment (Docker/Kubernetes) - Network isolation (cannot reach internet) - Non-root user - No access to sensitive paths ## Quick Start ### 1. Initialize Ralph in Your Project ```bash # Run the init script to scaffold Ralph files ./ralph-init.sh ``` This creates: - `RALPH_PROMPT.md` - The prompt fed to Claude each iteration - `IMPLEMENTATION_PLAN.md` - Task tracking file - `ralph.sh` - The main loop script - `ralph-sandbox.sh` - Docker wrapper - `Dockerfile.ralph` - Sandbox container definition ### 2. Define Your Work ```bash # Create specs directory for requirements mkdir -p specs # Write your requirements cat > specs/my-feature.md << 'EOF' ## Feature: User Dashboard ### Requirements - Show user's recent activity - Display usage statistics - Allow date range filtering EOF # Update the implementation plan cat > IMPLEMENTATION_PLAN.md << 'EOF' ## Tasks - [ ] Create Dashboard component - [ ] Add activity feed API endpoint - [ ] Implement date range picker - [ ] Write tests for dashboard EOF ``` ### 3. Run Ralph (In Sandbox) ```bash # Recommended: Use the Docker wrapper ./ralph-sandbox.sh # With iteration limit ./ralph-sandbox.sh . 20 # Check progress from another terminal tail -f ralph.log git log --oneline -10 ``` ### 4. Review Results ```bash # See what Ralph did git log --oneline # Check task completion cat IMPLEMENTATION_PLAN.md # Verify tests pass pytest ``` ## How It Works ``` ┌─────────────────────────────────────────────────────────────────┐ │ EXTERNAL BASH LOOP │ │ │ │ while :; do │ │ ┌─────────────────────────────────────────────────┐ │ │ │ CLAUDE SESSION │ │ │ │ │ │ │ │ 1. Read RALPH_PROMPT.md │ │ │ │ 2. Check IMPLEMENTATION_PLAN.md │ │ │ │ 3. Pick a task, implement it │ │ │ │ 4. Run tests, commit changes │ │ │ │ 5. Context fills → Session ends │ │ │ └─────────────────────────────────────────────────┘ │ │ ↓ │ │ Git commit saves progress │ │ Loop restarts with fresh context │ │ done │ └─────────────────────────────────────────────────────────────────┘ ``` ## Files Reference ### RALPH_PROMPT.md The prompt loaded each iteration. Customize this for your use case: ```markdown # Ralph Mode Instructions You are operating in autonomous Ralph mode. ## Each Iteration 1. Read IMPLEMENTATION_PLAN.md and git log 2. Pick ONE pending task, mark it in-progress 3. Implement fully with tests 4. Mark complete, commit changes ## Rules - Never skip tests - Commit after each meaningful change - If blocked, document why and continue ``` ### IMPLEMENTATION_PLAN.md Persistent task tracking (survives context resets): ```markdown ## Tasks - [x] Task 1 (completed in iteration 1) - [x] Task 2 (completed in iteration 2) - [ ] Task 3 (in progress) - [ ] Task 4 (pending) ``` ### ralph.sh The main loop with sandbox enforcement. Key features: - Refuses to run outside sandbox - Configurable iteration limits - Git commits after each iteration - Graceful shutdown handling ### ralph-sandbox.sh Docker wrapper that: - Builds sandbox image if needed - Mounts only project directory - Disables network (`--network none`) - Sets resource limits (memory, CPU, PIDs) - Drops all capabilities ## Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `RALPH_MAX_ITERATIONS` | `0` (unlimited) | Stop after N iterations | | `RALPH_MODEL` | `opus` | Claude model to use | | `RALPH_COST_LIMIT` | `50.00` | Max spend in USD (with cost monitor hook) | | `ANTHROPIC_API_KEY` | optional | API key (not needed with Claude Code subscription) | ### Sandbox Override (Dangerous) Only for custom sandbox environments you've verified: ```bash RALPH_I_KNOW_WHAT_IM_DOING=sandboxed ./ralph.sh ``` ## Best Practices ### Prompt Engineering 1. **Be specific** - Tell Claude exactly what to do each iteration 2. **Single task focus** - "Pick ONE task" prevents context bloat 3. **Require tests** - Include testing in the prompt 4. **Track progress** - Use IMPLEMENTATION_PLAN.md as shared state ### Task Decomposition Break large tasks into small, atomic pieces: ```markdown ## Bad - [ ] Implement user authentication ## Good - [ ] Create User model with email, password_hash - [ ] Add POST /api/register endpoint - [ ] Add POST /api/login endpoint - [ ] Add password reset flow - [ ] Add JWT middleware - [ ] Write auth tests ``` ### Monitoring ```bash # Watch iterations in real-time tail -f ralph.log # Check commits watch -n 5 'git log --oneline -10' # Monitor resource usage docker stats ``` ## Safety Hooks (Recommended) Install these hooks for additional safety: ```bash # Block dangerous operations skillpack hooks install ralph-safety-check # Track API costs skillpack hooks install ralph-cost-monitor ``` ## Troubleshooting ### Ralph won't start Check sandbox detection output. You need at least 3 checks passing: - Container detected - Network isolated - Non-root user - No sensitive path access ### Ralph gets stuck on a task 1. Check `ralph.log` for errors 2. Update `IMPLEMENTATION_PLAN.md` to unblock 3. Add clarifying notes to `RALPH_PROMPT.md` ### Runaway iterations Set `MAX_ITERATIONS` or use the cost monitor hook: ```bash ./ralph-sandbox.sh . 20 # Stop after 20 iterations ``` ## References - [Original Ralph Wiggum Technique](https://github.com/ghuntley/how-to-ralph-wiggum) - [Geoffrey Huntley's Blog](https://ghuntley.com/ralph/) - [VentureBeat Coverage](https://venturebeat.com/technology/how-ralph-wiggum-went-from-the-simpsons-to-the-biggest-name-in-ai-right-now)