Open Ralph Wiggum – Der vollständige Guide
Open Ralph Wiggum ist ein CLI-Wrapper, der die sogenannte „Ralph-Wiggum-Technik" automatisiert: Ein AI-Coding-Agent bekommt denselben Prompt immer wieder, bis die Aufgabe erledigt ist. Zwischen den Iterationen sieht der Agent seine eigenen Datei-Änderungen und die Git-History – er kann sich also selbst korrigieren und schrittweise vorankommen. Open Ralph Wiggum unterstützt 5 Agents (Claude Code, Codex, Copilot CLI, Cursor Agent, OpenCode) und kann diese sogar rotieren, um Modelle direkt zu vergleichen.
Repo: Th0rgal/open-ralph-wiggum · Lizenz: MIT
… du mehrere Agents/Modelle in einer Schleife rotieren willst und dabei eine schlanke, agent-agnostische CLI bevorzugst. Wenn du noch nicht entschieden hast, welche Ralph-Variante du nimmst – lies erst die Ralph-Wiggum-Technik – Gesamtübersicht. Sie vergleicht alle 6 großen Implementierungen (snarktank/ralph, ralph-loop-Plugin, open-ralph-wiggum, ralphex, ralph-orchestrator, ralphy).
1. Was ist Open Ralph Wiggum?​
Klassische AI-Coding-Sessions laufen interaktiv: Du schreibst, der Agent antwortet, du korrigierst. Ralph dreht das Ganze um – du gehst Kaffee trinken, und der Agent rödelt sich durch eine bekannte Aufgabe. Die zentrale Schleife sieht so aus:
- Prompt an den Agent schicken
- Agent ändert Dateien, ruft Tools auf, schreibt Code
- CLI prĂĽft, ob im Output das Completion-Promise (z. B.
COMPLETE) auftaucht - Wenn nicht → Loop neu starten (Agent sieht seine eigenen Änderungen + Git-History)
- Wenn ja → fertig
Warum funktioniert das?​
- Selbstkorrektur durch Diff-Lesen – der Agent sieht beim nächsten Lauf, was er beim letzten Mal gemacht hat
- Tests als Wahrheit – wenn dein Prompt sagt „läuft, wenn
pnpm testgrün ist", iteriert der Agent gegen die Realität, nicht gegen sein eigenes Halluzinationsbild - Inkrementeller Fortschritt – große Tasks zerfallen über Iterationen in kleine Häppchen
Open Ralph Wiggum im Ralph-Universum​
Es gibt mehrere Ralph-Implementierungen – jede mit anderem Schwerpunkt. Hier die Kurzfassung; die ausführliche Diskussion findest du in der Gesamtübersicht.
| Aspekt | open-ralph-wiggum | snarktank/ralph | ralphex | ralph-orchestrator | ralphy |
|---|---|---|---|---|---|
| Sprache | Bun + TS | Bash | Go | Rust + TS | TS + Bash |
| Agents | 5 | 2 (Amp, Claude) | 1 + Wrapper | 7 | 8 |
| Agent-Rotation | ✅ pro Iteration | – | – | – | – (parallel) |
| Multi-Phase Reviews | – | – | ✅ (5 Review-Agents) | – | – |
| Parallelität | – | – | Worktrees | – | ✅ (--parallel) |
| Web-Dashboard | – | – | ✅ | ✅ (Alpha) | – |
| MCP-Server | – | – | – | ✅ | – |
| Telegram-Steering | – | – | – | ✅ (RObot) | – |
| PRD-Format | freier Prompt + Tasks-Modus | prd.json + progress.txt | Markdown-Plan mit ### Task N | YAML/PDD | MD/YAML/JSON/Issues |
| Sweet-Spot | Modelle vergleichen | Bash-Pragmatik, viel Community | Multi-Phase-Review, Enterprise | Hat-System, MCP-Stack | Parallele Branches + PRs |
| Stars (Mai 2026) | – | 18.7k | 1.1k | 2.8k | 2.8k |
Sein Alleinstellungsmerkmal ist die --rotation: zwischen den Iterationen wechselt der Agent (z. B. Claude → Codex → OpenCode). Das ergibt heterogene Lösungspfade und reduziert die Wahrscheinlichkeit, dass ein einzelnes Modell in einer Sackgasse stecken bleibt. Keine andere Ralph-Implementierung hat das eingebaut.
2. Voraussetzungen​
- Bun (Runtime, Pflicht) –
curl -fsSL https://bun.sh/install | bash - Mindestens eine Agent-CLI auf dem Pfad:
claude(Claude Code)codex(OpenAI Codex CLI)copilot(GitHub Copilot CLI)cursor-agent(Cursor headless)opencode(Open-Source-Default)
- Git-Repo im aktuellen Verzeichnis (fĂĽr History-basierte Selbstkorrektur)
Open Ralph Wiggum ist in TypeScript geschrieben und nutzt Bun als Runtime statt Node – der Cold-Start ist deutlich schneller, was bei tausenden Iterationen pro Loop tatsächlich zählt.
3. Installation​
- npm (empfohlen)
- Bun
- Aus dem Quellcode
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
Verifizieren​
ralph --help # Kommandos auflisten
ralph --init-config # Default-Config schreiben
which claude codex # Agent-CLIs erreichbar?
Ralph löst auf Windows automatisch .cmd-Endungen für npm-installierte CLIs auf – du musst nichts manuell auf den PATH legen.
4. Erster Loop in 30 Sekunden​
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
Was passiert dabei:
- Ralph startet
claudemit deinem Prompt - Claude legt die Dateien an
- Output enthält
COMPLETE→ Ralph stoppt - Du hast einen funktionierenden Mini-Build, ohne einen einzigen Tastendruck
--max-iterationsOhne Limit kann ein Loop stundenlang laufen und dabei Tokens kosten. Faustregel: --max-iterations 10 bis 20 für die meisten Tasks. Erhöhe nur, wenn du weißt, was du tust.
5. Agents & Modelle​
Unterstützte Agents​
| Agent | Flag | Hinweise |
|---|---|---|
| Claude Code | --agent claude-code | Beste Qualität für komplexe Refactors, Sonnet/Opus |
| Codex | --agent codex | OpenAIs Coding-Modell, schnell |
| Copilot CLI | --agent copilot | GitHub-integriert, gut fĂĽr Repo-Kontext |
| Cursor Agent | --agent cursor-agent | Headless-Variante des Cursor-Editors |
| OpenCode | --agent opencode | Open-Source, Default, modell-agnostisch |
Modell überschreiben​
ralph "..." --agent claude-code --model claude-opus-4-7
ralph "..." --agent codex --model gpt-5
ralph "..." --agent opencode --model openai/gpt-4o
Custom Binary-Pfade (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 – Modelle gegeneinander testen​
Der vielleicht spannendste Modus: rotiere zwischen Agents/Modellen. Pro Iteration wird ein anderer Agent angesetzt.
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
Was du dadurch bekommst:
- Heterogene Lösungsansätze – Claude refactort, Codex schreibt frische Tests, OpenCode räumt auf
- Robustheit – ein Modell kommt in eine Sackgasse, das nächste sieht den Diff und korrigiert
- Vergleichswerte – im
--status-Dashboard siehst du, welcher Agent wieviele Tool-Calls/Iterationen verbraucht hat
--agent und --model werden ignoriert. Die Rotations-Liste ist alleinige Wahrheit.
7. Tasks-Modus – große Projekte zerlegen​
FĂĽr alles, was zu groĂź fĂĽr einen einzelnen Prompt ist, gibt es den Tasks-Modus.
ralph "Baue eine REST-API mit Auth, CRUD und Tests laut PRD.md" \
--tasks \
--agent claude-code \
--max-iterations 50
Wie es funktioniert​
- Tasks werden in
.ralph/ralph-tasks.mdgepflegt - Eine Task pro Iteration – der Agent fokussiert
- Default-Promise:
READY_FOR_NEXT_TASK(stattCOMPLETE) - Status-Marker:
[ ]offen ·[/]in Arbeit ·[x]fertig
Tasks von außen verwalten​
ralph --list-tasks
ralph --add-task "Rate-Limiting via Redis hinzufĂĽgen"
ralph --remove-task 3
8. Live-Steuerung des Loops​
Während der Loop läuft, kannst du in einem zweiten Terminal eingreifen.
ralph --status # Was läuft, wieviel Zeit, welche Tools
ralph --add-context "Nutze Vitest, nicht Jest" # Hinweis injizieren
ralph --clear-context # Hinweis verwerfen
--add-context schreibt in .ralph/ralph-context.md. Der Hinweis fließt in die nächste Iteration ein – der laufende Tool-Call wird nicht unterbrochen.
Status-Dashboard zeigt​
- Iteration, Elapsed Time, Original-Prompt
- Pending Context (was beim nächsten Lauf injiziert wird)
- Aktuelle Tasks (im Tasks-Modus)
- Letzte 5 Iterationen mit Tool-Counts (Bash, Write, Read, Edit) und Dauer
- Struggle-Indicators – warnt, wenn der Agent festhängt (keine File-Changes, gleiche Errors)
9. Custom Prompt-Templates​
Wenn du den Standard-Prompt-Header anpassen willst, ĂĽbergib ein Template:
ralph "..." --prompt-template ./my-template.md
Verfügbare Variablen​
| Variable | Bedeutung |
|---|---|
{{iteration}} | aktuelle Iteration |
{{max_iterations}} | Limit |
{{min_iterations}} | Minimum vor erlaubtem Abschluss |
{{prompt}} | dein Task-Prompt |
{{completion_promise}} | Completion-Signal (Default COMPLETE) |
{{abort_promise}} | Abort-Signal |
{{task_promise}} | Task-Completion-Signal (Tasks-Modus) |
{{context}} | injizierter Mid-Loop-Kontext |
{{tasks}} | Task-Liste (Tasks-Modus) |
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 — aktiver Loop-Zustand
- ralph-history.json — Iterations-Metriken
- ralph-context.md — Pending Context
- ralph-tasks.md — Tasks-Liste (Tasks-Modus)
- ralph-questions.json — offene Rückfragen
.ralph/ in .gitignoreDer Ordner enthält volatilen Loop-State – nicht committen. Ein Eintrag in .gitignore reicht. Das Repo selbst (also die Code-Änderungen) ist davon unberührt.
11. Wichtige Flags – Cheatsheet​
# Loop-Steuerung
--agent <name> # Agent wählen
--model <name> # Modell ĂĽberschreiben
--rotation "a:m,b:m" # Agent-Rotation
--max-iterations N # Hartes Limit
--min-iterations N # FrĂĽhestens nach N abschlieĂźen
--completion-promise "STRING" # Default: COMPLETE
--abort-promise "STRING" # frĂĽher Abbruch
--prompt-file, -f <path> # Prompt aus Datei
--prompt-template <path> # eigenes Template
--tasks, -t # Tasks-Modus
# Output
--no-stream # Output am Ende (statt Streaming)
--verbose-tools # Alle Tool-Operationen sichtbar
--questions / --no-questions # interaktive RĂĽckfragen (Default: an)
# Sicherheit / Verhalten
--allow-all / --no-allow-all # Tool-Permissions (Default: allow)
--no-plugins # OpenCode: Plugins aus
--no-commit # Keine Auto-Commits
--config <path> # Custom Agent-Config
--init-config [path] # Default-Config schreiben & exit
# Live-Steuerung (in zweitem Terminal)
--status
--add-context "TEXT"
--clear-context
--list-tasks
--add-task "TEXT"
--remove-task <index>
12. Sicherheit – Pflichtlektüre​
--allow-all ist DefaultRalph approved Tool-Calls des Agents standardmäßig automatisch. Das ist der Punkt der ganzen Übung – sonst gäbe es keine autonome Schleife. Aber: der Agent kann alles, was du in der Shell könntest.
Mitigationen:
- Loops nur in dedizierten Repos laufen lassen, nie im Home-Verzeichnis
- Sensible Repos vorher in eine VM oder Container klonen (Docker, Daytona, sandboxed.sh)
- API-Keys via
.env– nicht in Prompts, nicht im Repo - Bei Unsicherheit:
--no-allow-all→ interaktive Bestätigung (zerstört zwar Autonomie, aber sicher)
Per Default committet Ralph nach jeder Iteration. Das ist exzellent fürs Debugging (git log zeigt jede Iteration), aber pollutet die History. Für „echte" Branches → --no-commit und am Ende manuell squashen.
Wann Open Ralph Wiggum nicht das richtige Tool ist​
- Aufgaben, die menschliches Urteil brauchen (Designentscheidungen, Trade-offs)
- Production-Debugging mit echten Usern – hier zählt Vorsicht > Geschwindigkeit
- Tasks ohne verifizierbares Erfolgskriterium – ohne Tests oder Linter dreht sich der Loop bis zum Iterations-Limit, ohne dass du weißt, ob er „fertig" ist
13. Prompt-Best-Practices​
Ein guter Ralph-Prompt hat 4 Bestandteile:
## 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.
Bei umfangreichen Feature-Listen reduziert ein strukturiertes JSON-Schema (Features als Liste mit id, title, acceptance: []) die Tendenz des Agents, vorhandene Tests umzuschreiben, statt sie zu erfĂĽllen.
14. Häufige Probleme​
| Problem | Lösung |
|---|---|
bun: command not found | Bun installieren (curl -fsSL https://bun.sh/install | bash) |
claude / codex / copilot: command not found | Agent-CLI separat installieren, ggf. RALPH_*_BINARY setzen |
| Loop hört nie auf | --max-iterations setzen; Completion-Promise klar im Prompt |
| Agent hängt fest, ändert nichts | Status checken (--status) → Struggle-Warnings; --add-context mit Hinweis |
| Auto-Commits explodieren | --no-commit + am Ende git rebase -i |
| „Tests grün, aber falsch" | Agent hat Tests umgeschrieben → Akzeptanzkriterien strenger formulieren, JSON-PRD |
| Token-Kosten zu hoch | --max-iterations strenger, kĂĽrzeres Template, kleineres Modell |
15. Weiterführend​
Open Ralph Wiggum
- GitHub: Th0rgal/open-ralph-wiggum
Ralph-Universum (siehe GesamtĂĽbersicht)
- snarktank/ralph – populärste Bash-Variante (Ryan Carson)
- anthropics/claude-plugins-official → ralph-loop – offizielles Claude-Code-Plugin (Stop-Hook, in-session Loop)
- umputun/ralphex – Go, Multi-Phase-Reviews
- mikeyobrien/ralph-orchestrator – Rust, Hat-System, MCP, Telegram
- michaelshimeles/ralphy – parallele Worktrees + PRs
- Original-Technik: Geoffrey Huntleys Blog – „Ralph Wiggum as a Software Engineer"
- Sandboxing: sandboxed.sh
Agent-CLIs, die Ralph nutzt
„Run the same prompt in a loop until the agent's diff catches up with reality."