---
title: "setup-ralph"
description: "A Claude Code skill that sets up [Ralph Wiggum loops](https://ghuntley.com/ralph/) - Geoffrey Huntley's autonomous AI coding technique."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/readme-664
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:36:48.879Z
license: CC-BY-4.0
attribution: "setup-ralph — Claudary (https://claudary.paisolsolutions.com/skills/readme-664)"
---

# setup-ralph
A Claude Code skill that sets up [Ralph Wiggum loops](https://ghuntley.com/ralph/) - Geoffrey Huntley's autonomous AI coding technique.

## Overview

# setup-ralph

A Claude Code skill that sets up [Ralph Wiggum loops](https://ghuntley.com/ralph/) - Geoffrey Huntley's autonomous AI coding technique.

## What is Ralph?

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

```bash
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:**
```bash
./loop.sh plan          # Generate implementation plan
./loop.sh               # Build until complete
./loop.sh 20            # Build max 20 iterations
```

**Docker mode (isolated):**
```bash
./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)

```bash
# 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:
```bash
./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](https://ghuntley.com/ralph/).

## License

MIT

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-664) · https://claudary.paisolsolutions.com