Agent skill

ralph-wiggum

Autonomous AI coding loop for unattended development - lets Claude work continuously on tasks while you sleep, with mandatory sandbox enforcement for safety

View SKILL.md on GitHub Repository
Stars 23
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/jkitchin/skillz/tree/main/skills/development/ralph-wiggum

SKILL.md

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 sonnet 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
skillz hooks install ralph-safety-check

# Track API costs
skillz 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

Didn't find tool you were looking for?

Be as detailed as possible for better results