setup-ralph

A Claude Code skill that sets up Ralph Wiggum loops - Geoffrey Huntley's autonomous AI coding technique.

What is Ralph?

Ralph is an autonomous coding methodology where Claude runs in a loop:

while :; do cat PROMPT.md | claude -p --dangerously-skip-permissions; done

Each iteration:

1. Reads specs and implementation plan
2. Picks the most important task
3. Implements it
4. Runs validation (tests, types, lint, build)
5. Commits changes
6. Exits → loop restarts with fresh context

The key insight: fresh context every iteration prevents hallucination accumulation and context poisoning.

Features

• Two-phase workflow: Planning mode (gap analysis) → Building mode (implementation)
• Docker isolation: Run Ralph in a container so it can't touch your system files
• OAuth token handling: Automatic token loading for headless mode
• Iteration summaries: See commits, files changed, and progress after each task
• Stuck detection: Auto-skips tasks after 3 failed attempts
• Session reports: Summary of what was accomplished when the loop ends
• File logging: tail -f ralph.log to watch progress

Usage

In Claude Code, run:

/setup-ralph

Then follow the prompts to configure:

• Project directory
• Tech stack (determines validation commands)
• Backpressure level (tests only → full validation)
• Docker mode (yes/no)

Generated Files

your-project/
├── loop.sh              # Main loop script
├── loop-docker.sh       # Docker-wrapped loop (if selected)
├── Dockerfile           # Container definition (if selected)
├── PROMPT_plan.md       # Planning mode instructions
├── PROMPT_build.md      # Building mode instructions
├── AGENTS.md            # Operational learnings (you update this)
├── IMPLEMENTATION_PLAN.md  # Task list (generated by planning)
├── specs/               # Your requirement docs go here
└── src/                 # Code goes here

Running the Loop

Direct mode:

./loop.sh plan          # Generate implementation plan
./loop.sh               # Build until complete
./loop.sh 20            # Build max 20 iterations

Docker mode (isolated):

./loop-docker.sh --build-image   # First time only
./loop-docker.sh plan            # Generate plan
./loop-docker.sh                 # Build in container

Iteration Output

After each iteration, you'll see:

━━━ Iteration 5 Complete (2m 34s) ━━━
✅ Commit: abc1234 [city] Add procedural building generation
📁 Files: +2 new, ~3 modified
   🆕 src/CityGenerator.ts
   🆕 src/Building.ts
   ✏️  src/Game.ts
   ✏️  src/World.ts
📊 Progress: 5/22 tasks (23%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Your Role

Sit on the loop, not in it.

You:

• Write specs in specs/ (one file per topic)
• Watch for failure patterns
• Update AGENTS.md with learnings
• Ctrl+C to stop when needed

You don't:

• Jump in to fix code manually
• Interfere with the autonomous process

When Ralph struggles repeatedly, update the environment (specs, AGENTS.md, prompts) rather than fixing code directly.

OAuth Setup (Required for Headless Mode)

# Generate token
claude setup-token

# Save it
echo "sk-ant-oat01-YOUR-TOKEN" > ~/.claude-oauth-token
chmod 600 ~/.claude-oauth-token

The loop scripts automatically load this token.

Docker Mode

Docker mode runs Claude in an isolated container:

• ✅ Can only access the project directory
• ✅ Can't modify system files
• ✅ Uses your Claude Max subscription via OAuth token
• ✅ Non-root user (required for --dangerously-skip-permissions)

First time setup:

./loop-docker.sh --build-image

Then just run ./loop-docker.sh - switches seamlessly between Docker and direct mode.

Writing Good Specs

Each spec file should pass the "one sentence without 'and'" test:

• ✅ specs/authentication.md - "User login with credentials"
• ✅ specs/session-management.md - "Session lifecycle and validation"
• ❌ specs/user-system.md - "Auth AND profiles AND billing" (too broad)

Include:

• Clear requirements
• Examples where helpful
• Acceptance criteria
• NOT implementation details (that's Ralph's job)

Credits

Based on Geoffrey Huntley's Ralph Wiggum technique.

License

MIT