ralph-wiggum-loop

# The Ralph Wiggum Loop

> "Ralph is a loop." — Geoffrey Huntley

## The Core Insight: Context Rotation

LLM context windows are like memory with `malloc()` but no `free()`.

As an agent works, context fills:
```
Start:        [PROMPT]
Read files:   [PROMPT][file1][file2][file3]
Tool calls:   [PROMPT][file1][file2][file3][results][more_results]
Errors:       [PROMPT][file1][file2][file3][results][more_results][stack_trace]
Eventually:   [PROMPT][file1][file2][...everything...][gutter]
```

When context fills with stale information, the agent enters the **"gutter"** — poor decisions because critical information is buried. There's no way to selectively free context.

**The solution: loop termination IS the `free()`.**

```
Iteration 1: Fresh context → work → commit → EXIT (freed)
Iteration 2: Fresh context → work → commit → EXIT (freed)
Iteration 3: Fresh context → work → commit → EXIT (freed)
```

Each iteration:
1. Starts with **zero memory** from previous iteration
2. Loads only the prompt (small, deterministic)
3. Reads current state from **disk** (git, files)
4. Does **ONE task**
5. Commits progress
6. Exits → context garbage collected

**Progress persists in files and git, not in context.**

## The CLI: gumloop

```bash
# Install
curl -fsSL https://raw.githubusercontent.com/adriancodes/gumloop/main/install.sh | bash

# Quick start
cd my-project
gumloop init
gumloop run -p "Fix all failing tests" --choo-choo
```

### Run Commands

```bash
gumloop run -p "Fix the tests"                # Run once with inline prompt
gumloop run --prompt-file PROMPT.md            # Run once with prompt file
gumloop run --choo-choo -p "Fix bugs"          # Loop until no changes
gumloop run --choo-choo 20 -p "Migrate to TS"  # Loop, max 20 iterations
gumloop run --model sonnet -p "..."            # Use a specific model
gumloop run --verify "npm test" -p "..."       # Run tests after each iteration
gumloop run --memory --choo-choo -p "..."      # Session memory between runs
```

### Other Commands

```bash
gumloop init                    # Interactive setup wizard
gumloop config show             # Show effective merged config
gumloop config set cli codex    # Set project config
gumloop memory show             # Display session memory
gumloop memory clear            # Delete session memory file
gumloop recover                 # Discard uncommitted changes
gumloop recover 3               # Reset last 3 commits
gumloop update                  # Update to latest version
gumloop uninstall               # Remove gumloop
```

### Supported Agents

```bash
gumloop run --cli claude -p "..."       # Claude Code (default)
gumloop run --cli codex -p "..."        # OpenAI Codex
gumloop run --cli gemini -p "..."       # Google Gemini
gumloop run --cli cursor -p "..."       # Cursor Agent CLI
gumloop run --cli opencode -p "..."     # OpenCode
gumloop run --cli ollama -p "..."       # Ollama (local)
```

### Loop Behavior

- Without `--choo-choo`: runs once and exits
- With `--choo-choo`: loops until no git changes detected
- Stuck detection: exits after N iterations with changes but no commits (default: 3)
- `--memory`: saves session state so the next run picks up where it left off
- Ctrl+C to exit cleanly at any time

## Why One Task Per Loop

Multiple tasks = context accumulation = gutter state.

One task = fresh context = sharp reasoning = atomic commits.

Your prompt should say "pick the most important task" not "do all tasks."

## The Philosophy

### Deterministically Bad

> "That's the beauty of Ralph - the technique is deterministically bad in an undeterministic world."

Ralph will fail. Failures are predictable and fixable. Better than succeeding unpredictably.

### Eventual Consistency

If the agent keeps correcting itself, it will eventually converge. Each iteration sees results of previous iterations through git and files.

### LLMs Are Mirrors

Success depends on writing good prompts. Quality of output reflects quality of input.

### Monolithic

Single process, single repository, one task per loop. NOT multi-agent orchestration or loops within loops.

## Tuning: The Playground Metaphor

> "Ralph is given instructions to construct a playground. Ralph comes home bruised because he fell off the slide, so you add a sign: 'SLIDE DOWN, DON'T JUMP.' Eventually all Ralph thinks about is the signs — that's a tuned prompt."

Start minimal. Observe failures. Add specific guardrails.

## Minimal Setup

```bash
mkdir project && cd project
git init

# Run once
gumloop run -p "What does this codebase do?"

# Loop until done
gumloop run -p "Fix all failing tests" --choo-choo
```

## Spec-Driven Workflow

For large projects, use three phases: **Spec → Plan → Execute**.

**1. Create Spec** — Write `SPEC.md` with architecture, components, task backlog.

**2. Generate Plan** — Run once to create lightweight task list:
```bash
gumloop run -p "Read SPEC.md. Create IMPLEMENTATION_PLAN.md with checkboxes for each task. Planning only."
```

**3. Execute from Plan** — Loop with a prompt that references both:
```bash
gumloop run --choo-choo -p "Read IMPLEMENTATION_PLAN.md. Find first unchecked task. Read SPEC.md for details. Implement it. Mark done. Commit with task ID."
```

The plan is a lightweight index into the heavy spec. Agent reads plan to know *what*, spec to know *how*.

## Safety

**Built-in checks:**
- Refuses dangerous directories (~, /, /etc, /usr, /var, /tmp)
- Requires git repository
- Warns before choo-choo mode in home subdirectories

**Git is your safety net:**
```bash
gumloop recover       # Discard uncommitted changes
gumloop recover 3     # Reset last 3 commits
git reset --hard      # Instant recovery
```

**For true isolation:** E2B, Fly Sprites, Modal, dedicated VM.

## When to Use

**Good for:** Greenfield, reverse engineering, refactors, migrations, test coverage, documentation, overnight work.

**Not ideal for:** Judgment-heavy work, unclear completion criteria, highly exploratory research.

## References

- `references/context-engineering.md` — Why the loop works
- `references/workflow-patterns.md` — Two-mode, specs directories
- `references/prompt-templates.md` — Starter prompts
- `references/tuning-guide.md` — Guardrail patterns
- `references/safety.md` — Safety considerations