Open Ralph Wiggum – The Complete Guide

What's this about?

Open Ralph Wiggum is a CLI wrapper that automates the so-called "Ralph Wiggum technique": an AI coding agent is given the same prompt over and over until the task is done. Between iterations, the agent sees its own file changes and the Git history – so it can self-correct and make incremental progress. Open Ralph Wiggum supports 5 agents (Claude Code, Codex, Copilot CLI, Cursor Agent, OpenCode) and can even rotate between them to compare models head-to-head.

Repo: Th0rgal/open-ralph-wiggum · License: MIT

You're in the right place if …

… you want to rotate multiple agents/models in a loop and prefer a lean, agent-agnostic CLI. If you haven't yet decided which Ralph variant to use, first read the Ralph Wiggum technique – overview. It compares all 6 major implementations (snarktank/ralph, ralph-loop plugin, open-ralph-wiggum, ralphex, ralph-orchestrator, ralphy).

1. What is Open Ralph Wiggum?

Classic AI coding sessions run interactively: you type, the agent answers, you correct. Ralph flips that around – you go grab a coffee, and the agent grinds through a well-defined task. The core loop looks like this:

Send the prompt to the agent
Agent edits files, calls tools, writes code
CLI checks whether the completion promise (e.g. COMPLETE) shows up in the output
If not → restart the loop (agent sees its own changes + Git history)
If yes → done

Why does this work?

Self-correction through reading diffs – on the next run, the agent sees what it did last time
Tests as ground truth – if your prompt says "done when pnpm test is green", the agent iterates against reality, not against its own hallucinated view
Incremental progress – large tasks decompose into bite-sized chunks across iterations

Open Ralph Wiggum in the Ralph universe

There are several Ralph implementations – each with a different focus. Here's the short version; for the full discussion see the overview.

Aspect	open-ralph-wiggum	snarktank/ralph	ralphex	ralph-orchestrator	ralphy
Language	Bun + TS	Bash	Go	Rust + TS	TS + Bash
Agents	5	2 (Amp, Claude)	1 + wrapper	7	8
Agent rotation	✅ per iteration	–	–	–	– (parallel)
Multi-phase reviews	–	–	✅ (5 review agents)	–	–
Parallelism	–	–	Worktrees	–	✅ (`--parallel`)
Web dashboard	–	–	✅	✅ (alpha)	–
MCP server	–	–	–	✅	–
Telegram steering	–	–	–	✅ (RObot)	–
PRD format	free prompt + tasks mode	`prd.json` + `progress.txt`	Markdown plan with `### Task N`	YAML/PDD	MD/YAML/JSON/issues
Sweet spot	Comparing models	Bash pragmatism, big community	Multi-phase review, enterprise	Hat system, MCP stack	Parallel branches + PRs
Stars (May 2026)	–	18.7k	1.1k	2.8k	2.8k

What sets open-ralph-wiggum apart

Its unique selling point is --rotation: between iterations the agent switches (e.g. Claude → Codex → OpenCode). This produces heterogeneous solution paths and reduces the chance that a single model gets stuck in a dead end. No other Ralph implementation has this built in.

2. Prerequisites

Bun (runtime, required) – curl -fsSL https://bun.sh/install | bash
At least one agent CLI on the path:
- claude (Claude Code)
- codex (OpenAI Codex CLI)
- copilot (GitHub Copilot CLI)
- cursor-agent (Cursor headless)
- opencode (open-source default)
Git repo in the current directory (for history-based self-correction)

Why Bun?

Open Ralph Wiggum is written in TypeScript and uses Bun as its runtime instead of Node – cold start is noticeably faster, which actually matters when you have thousands of iterations per loop.

3. Installation

npm (recommended)
Bun
From source

npm install -g @th0rgal/ralph-wiggum
ralph --version

bun add -g @th0rgal/ralph-wiggum
ralph --version

git clone https://github.com/Th0rgal/open-ralph-wiggum.git
cd open-ralph-wiggum

# Linux / macOS
./install.sh

# Windows
.\install.ps1

Verify

ralph --help              # List commands
ralph --init-config       # Write default config
which claude codex        # Agent CLIs reachable?

Windows note

On Windows, Ralph automatically resolves .cmd extensions for npm-installed CLIs – you don't have to manually add anything to your PATH.

4. First loop in 30 seconds

mkdir demo && cd demo && git init

ralph "Erstelle eine TypeScript-Funktion add(a, b) in src/add.ts.
Schreibe einen Test in test/add.test.ts.
Führe 'bun test' aus. Wenn der Test grün ist, gib COMPLETE aus." \
  --agent claude-code \
  --max-iterations 5

What happens here:

Ralph starts claude with your prompt
Claude creates the files
Output contains COMPLETE → Ralph stops
You have a working mini-build without a single keystroke

ALWAYS set --max-iterations

Without a limit, a loop can run for hours and rack up token costs. Rule of thumb: --max-iterations 10 to 20 for most tasks. Only raise it when you know what you're doing.

5. Agents & models

Supported agents

Agent	Flag	Notes
Claude Code	`--agent claude-code`	Best quality for complex refactors, Sonnet/Opus
Codex	`--agent codex`	OpenAI's coding model, fast
Copilot CLI	`--agent copilot`	GitHub-integrated, good for repo context
Cursor Agent	`--agent cursor-agent`	Headless variant of the Cursor editor
OpenCode	`--agent opencode`	Open-source, default, model-agnostic

Override the model

ralph "..." --agent claude-code --model claude-opus-4-7
ralph "..." --agent codex       --model gpt-5
ralph "..." --agent opencode    --model openai/gpt-4o

Custom binary paths (ENV)

Variable	Default
`RALPH_OPENCODE_BINARY`	`opencode`
`RALPH_CLAUDE_BINARY`	`claude`
`RALPH_CODEX_BINARY`	`codex`
`RALPH_COPILOT_BINARY`	`copilot`
`RALPH_CURSOR_AGENT_BINARY`	`cursor-agent`

export RALPH_CLAUDE_BINARY="$HOME/.local/bin/claude-beta"
ralph "..." --agent claude-code

6. Agent rotation – pit models against each other

Probably the most exciting mode: rotate between agents/models. A different agent is used per iteration.

ralph "Implementiere und teste eine Bloom-Filter-Klasse in src/bloom.ts.
Test grün → COMPLETE." \
  --rotation "claude-code:claude-sonnet-4-6,codex:gpt-5,opencode:openai/gpt-4o" \
  --max-iterations 12

What you get out of it:

Heterogeneous approaches – Claude refactors, Codex writes fresh tests, OpenCode cleans up
Robustness – one model hits a dead end, the next one sees the diff and corrects course
Comparative metrics – in the --status dashboard you can see how many tool calls/iterations each agent consumed

With rotation:

--agent and --model are ignored. The rotation list is the sole source of truth.

7. Tasks mode – break down large projects

For anything too big for a single prompt, there's the tasks mode.

ralph "Baue eine REST-API mit Auth, CRUD und Tests laut PRD.md" \
  --tasks \
  --agent claude-code \
  --max-iterations 50

How it works

Tasks are maintained in .ralph/ralph-tasks.md
One task per iteration – the agent stays focused
Default promise: READY_FOR_NEXT_TASK (instead of COMPLETE)
Status markers: [ ] open · [/] in progress · [x] done

Manage tasks from the outside

ralph --list-tasks
ralph --add-task "Rate-Limiting via Redis hinzufügen"
ralph --remove-task 3

8. Live-controlling the loop

While the loop runs, you can step in from a second terminal.

ralph --status                          # What's running, how long, which tools

ralph --add-context "Nutze Vitest, nicht Jest"   # Inject a hint
ralph --clear-context                            # Discard the hint

--add-context writes to .ralph/ralph-context.md. The hint flows into the next iteration – the currently running tool call is not interrupted.

The status dashboard shows

Iteration, elapsed time, original prompt
Pending context (what will be injected on the next run)
Current tasks (in tasks mode)
The last 5 iterations with tool counts (Bash, Write, Read, Edit) and duration
Struggle indicators – warns when the agent is stuck (no file changes, same errors)

9. Custom prompt templates

If you want to customize the standard prompt header, pass a template:

ralph "..." --prompt-template ./my-template.md

Available variables

Variable	Meaning
`{{iteration}}`	current iteration
`{{max_iterations}}`	limit
`{{min_iterations}}`	minimum before completion is allowed
`{{prompt}}`	your task prompt
`{{completion_promise}}`	completion signal (default `COMPLETE`)
`{{abort_promise}}`	abort signal
`{{task_promise}}`	task completion signal (tasks mode)
`{{context}}`	injected mid-loop context
`{{tasks}}`	task list (tasks mode)

Minimal template

# Iteration {{iteration}} / {{max_iterations}}

## Aufgabe
{{prompt}}

## Wenn fertig
Gib **{{completion_promise}}** in deine letzte Output-Zeile.

## Aktueller Hinweis
{{context}}

10. State & storage

- ralph-loop.state.json — active loop state
- ralph-history.json — iteration metrics
- ralph-context.md — pending context
- ralph-tasks.md — task list (tasks mode)
- ralph-questions.json — open follow-up questions

.ralph/ in .gitignore

The folder contains volatile loop state – don't commit it. A single entry in .gitignore is enough. The repo itself (i.e. the code changes) is unaffected.

11. Important flags – cheatsheet

# Loop control
--agent <name>                   # Pick agent
--model <name>                   # Override model
--rotation "a:m,b:m"             # Agent rotation
--max-iterations N               # Hard limit
--min-iterations N               # Complete no earlier than N
--completion-promise "STRING"    # Default: COMPLETE
--abort-promise "STRING"         # Early abort
--prompt-file, -f <path>         # Prompt from file
--prompt-template <path>         # Custom template
--tasks, -t                      # Tasks mode

# Output
--no-stream                      # Output at the end (instead of streaming)
--verbose-tools                  # Show all tool operations
--questions / --no-questions     # Interactive follow-ups (default: on)

# Safety / behavior
--allow-all / --no-allow-all     # Tool permissions (default: allow)
--no-plugins                     # OpenCode: disable plugins
--no-commit                      # No auto-commits
--config <path>                  # Custom agent config
--init-config [path]             # Write default config & exit

# Live control (in a second terminal)
--status
--add-context "TEXT"
--clear-context
--list-tasks
--add-task "TEXT"
--remove-task <index>

12. Safety – required reading

--allow-all is the default

Ralph approves the agent's tool calls automatically by default. That's the whole point of the exercise – otherwise there'd be no autonomous loop. But: the agent can do anything you could do in your shell.

Mitigations:

Only run loops in dedicated repos, never in your home directory
Clone sensitive repos into a VM or container first (Docker, Daytona, sandboxed.sh)
API keys via .env – not in prompts, not in the repo
When in doubt: --no-allow-all → interactive confirmation (kills autonomy, but it's safe)

Auto-commit

By default, Ralph commits after every iteration. That's excellent for debugging (git log shows every iteration), but it pollutes the history. For "real" branches → --no-commit and squash manually at the end.

When Open Ralph Wiggum is not the right tool

Tasks that require human judgment (design decisions, trade-offs)
Production debugging with real users – caution beats speed here
Tasks without a verifiable success criterion – without tests or a linter, the loop spins until the iteration limit without you knowing whether it's actually "done"

13. Prompt best practices

A good Ralph prompt has 4 parts:

## Ziel
Implementiere die JWT-Auth laut PRD.md.

## Akzeptanzkriterien
1. POST /login gibt bei korrekten Credentials einen Bearer-Token zurück.
2. Geschützte Routen (/me) liefern bei fehlerhaftem Token 401.
3. `pnpm test` läuft grün.
4. `pnpm lint` läuft ohne Fehler.

## Verifikation
Führe `pnpm test && pnpm lint` aus, bevor du COMPLETE schreibst.

## Completion
Wenn alle Kriterien erfüllt sind, gib in der letzten Zeile `COMPLETE` aus.

JSON instead of Markdown for complex PRDs

For extensive feature lists, a structured JSON schema (features as a list with id, title, acceptance: []) reduces the agent's tendency to rewrite existing tests instead of satisfying them.

14. Common problems

Problem	Solution
`bun: command not found`	Install Bun (`curl -fsSL https://bun.sh/install \| bash`)
`claude / codex / copilot: command not found`	Install the agent CLI separately, set `RALPH_*_BINARY` if needed
Loop never stops	Set `--max-iterations`; make the completion promise explicit in the prompt
Agent is stuck, changes nothing	Check status (`--status`) → struggle warnings; `--add-context` with a hint
Auto-commits explode	`--no-commit` + `git rebase -i` at the end
"Tests green, but wrong"	Agent rewrote the tests → tighten the acceptance criteria, use a JSON PRD
Token costs too high	Stricter `--max-iterations`, shorter template, smaller model

15. Further reading

Open Ralph Wiggum

GitHub: Th0rgal/open-ralph-wiggum

Ralph universe (see the overview)

snarktank/ralph – most popular Bash variant (Ryan Carson)
anthropics/claude-plugins-official → ralph-loop – official Claude Code plugin (stop hook, in-session loop)
umputun/ralphex – Go, multi-phase reviews
mikeyobrien/ralph-orchestrator – Rust, hat system, MCP, Telegram
michaelshimeles/ralphy – parallel worktrees + PRs
Original technique: Geoffrey Huntley's blog – "Ralph Wiggum as a Software Engineer"
Sandboxing: sandboxed.sh

Agent CLIs that Ralph uses

Quote

"Run the same prompt in a loop until the agent's diff catches up with reality."

1. What is Open Ralph Wiggum?​

Why does this work?​

Open Ralph Wiggum in the Ralph universe​

2. Prerequisites​

3. Installation​

Verify​

4. First loop in 30 seconds​

5. Agents & models​

Supported agents​

Override the model​

Custom binary paths (ENV)​

6. Agent rotation – pit models against each other​

7. Tasks mode – break down large projects​

How it works​

Manage tasks from the outside​

8. Live-controlling the loop​

The status dashboard shows​

9. Custom prompt templates​

Available variables​

Minimal template​

10. State & storage​

11. Important flags – cheatsheet​

12. Safety – required reading​

When Open Ralph Wiggum is not the right tool​

13. Prompt best practices​

14. Common problems​

15. Further reading​