Zum Hauptinhalt springen

Ralph-Wiggum-Technik – Gesamtübersicht

Worum geht's?

Die Ralph-Wiggum-Technik ist der schlichteste, gleichzeitig produktivste agentische Trick im Werkzeugkasten 2025/2026: Lass den AI-Coding-Agent denselben Prompt in einer Schleife laufen, bis die Aufgabe erledigt ist. Geoffrey Huntley hat das Pattern in seinem Blog-Post „Ralph Wiggum as a Software Engineer" populär gemacht. Inzwischen gibt es mindestens 6 nennenswerte Implementierungen – von einer 200-Zeilen-Bash-Datei bis zum Multi-Phase-Go-Tool mit Web-Dashboard und Telegram-Bot. Dieser Guide ist die Landkarte.

1. Die Technik in einem Satz​

while true; do
  agent --prompt "$PROMPT"
  grep -q "<promise>COMPLETE</promise>" output.log && break
done

Mehr Magie ist nicht dahinter. Funktioniert deshalb, weil:

  • Der Agent jedes Mal frisch startet – keine Context-Degradation, kein Driften
  • Die Dateien aus der letzten Iteration bestehen bleiben – Git-History + Filesystem sind die Memory
  • Tests die Wahrheit sind – wenn der Prompt sagt „grün = fertig", iteriert der Agent gegen die Realität
  • Failures Daten sind – jede falsche Iteration hilft der nächsten, sich zu verbessern
Quote

„Ralph is a Bash loop." — Geoffrey Huntley

2. Warum es überhaupt funktioniert​

Problem traditioneller AI-SessionsRalphs Antwort
Context-Window läuft vollFrische Session pro Iteration → Context-Reset
Agent verliert den roten FadenPrompt ist immer gleich; Status liegt im Filesystem
„Halluziniert, dass es fertig ist"Tests/Linter bestimmen Completion, nicht das Modell
Ein Modell kommt in SackgasseRotation oder mehrere Reviews korrigieren
Mensch muss ständig „yes" klickenAuto-Approve in dedizierter Sandbox

3. Die 6 großen Implementierungen​

3.1 snarktank/ralph – die populäre Bash-Variante​

Repo: snarktank/ralph · Sprache: Bash + TypeScript-Skills · Stars: 18.7k · Lizenz: MIT

Autor: Ryan Carson – basiert explizit auf Geoffrey Huntleys Pattern.

snarktank/ralph ist die Variante, die in Tutorials, Y-Combinator-Threads und Twitter am häufigsten zitiert wird. Sie ist absichtlich einfach: ein Bash-Skript, eine Prompt-Datei, drei Persistenz-Files.

Architektur​

    • ralph.sh — die Bash-Schleife (Amp + Claude)
    • prompt.md — Anweisungen für Amp
    • CLAUDE.md — Anweisungen für Claude Code
    • prd.json — User-Stories mit pass/fail
    • progress.txt — append-only Lessons Learned
    • AGENTS.md — vom Agent gepflegte Patterns/Gotchas

Workflow​

  1. PRD generieren – Skill prd lädt eine Konversation, der Mensch beschreibt Anforderungen, Agent schreibt eine Markdown-PRD.
  2. In prd.json konvertieren – Skill ralph strukturiert User-Stories als Liste mit passes: false.
  3. Loop starten – ./scripts/ralph/ralph.sh [max_iterations] (Default: 10).
  4. Pro Iteration:
    • Branch von Spec aus erstellen
    • Höchste-Priorität-Story wählen, deren passes noch false ist
    • Story isoliert implementieren
    • Typecheck + Tests ausführen
    • Commit auf Erfolg, prd.json updaten, Erkenntnisse in progress.txt anhängen
  5. Wenn alle Stories passes: true → Output <promise>COMPLETE</promise> → Loop endet

Installation – drei Wege​

# 1. Direkt ins Projekt kopieren
mkdir -p scripts/ralph && cp ralph.sh prompt.md scripts/ralph/

# 2. Als globale Amp-Skills
~/.config/amp/skills/prd/
~/.config/amp/skills/ralph/

# 3. Als Claude-Code-Plugin (Marketplace)
/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

Unterstützte Tools​

  • Amp CLI (Default) – mit amp.experimental.autoHandoff: { context: 90 } für Auto-Handoff bei vollem Context
  • Claude Code – via --tool claude

Killer-Feature: AGENTS.md Auto-Update​

Nach jeder Iteration trägt der Agent selbst entdeckte Patterns, Gotchas und Konventionen in AGENTS.md ein. Spätere Iterationen (und menschliche Entwickler) profitieren von diesem akkumulierenden Wissen. Das ist die einfachste Form von Self-Improvement, die ich in Ralph-Implementierungen gesehen habe.

Wann nehmen?​

  • Du willst die Original-Erfahrung mit minimalen Abhängigkeiten
  • Du arbeitest mit Amp oder Claude Code, nicht mit GPT/Cursor
  • Du willst sehen, wie das Pattern intern funktioniert (Bash ist gut lesbar)
  • Du brauchst die größte Community + Beispiel-Repos

3.2 ralph-loop – das offizielle Claude-Code-Plugin​

Repo: anthropics/claude-plugins-official → ralph-loop

Anthropics offizielle, null-Abhängigkeit-Variante – ein Plugin, das in Claude Code selbst läuft.

Was es ist​

Statt einer externen Bash-Schleife nutzt das Plugin einen Stop-Hook: Wenn Claude versucht, die Session zu beenden, fängt der Hook das ab und füttert denselben Prompt erneut ins laufende Modell. Der Loop passiert innerhalb der aktuellen Session – kein zweites Terminal, kein Subprozess, kein Script.

Plugin-Struktur​

    • README.md

Bedienung​

# Aktivieren (in Claude Code)
/plugin install ralph-loop

# Loop starten
/ralph-loop "Build a REST API for todos. CRUD, validation, tests > 80% coverage. Output <promise>COMPLETE</promise> when done." \
  --completion-promise "COMPLETE" \
  --max-iterations 50

# Loop abbrechen
/cancel-ralph

Wie der Stop-Hook funktioniert​

1. /ralph-loop ruft Claude mit dem Prompt auf
2. Claude arbeitet, will Session beenden
3. Stop-Hook (hooks/stop-hook.sh) fängt das Exit ab
4. Hook injiziert den GLEICHEN Prompt nochmal
5. Claude liest seinen eigenen Diff + Git-Log und macht weiter
6. Loop endet bei: COMPLETE im Output / Max-Iterations / /cancel-ralph
Größter Vorteil: Null Setup

Kein Bun, kein Go, kein Cargo, kein Rust. Wenn du eh Claude Code nutzt, ist das die schnellste Option. Ein Plugin-Install und du hast Ralph.

Windows-Stolperfalle

Auf Windows scheitert der Stop-Hook gelegentlich mit wsl: Unknown key 'automount.crossDistro' oder execvpe(/bin/bash) failed. Workaround: ~/.claude/plugins/cache/.../hooks/hooks.json so anpassen, dass der Hook explizit Git-Bash nutzt:

"command": "\"C:/Program Files/Git/bin/bash.exe\" ${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"

Wichtig: Git/bin/bash.exe (mit PATH-Wrapper), nicht Git/usr/bin/bash.exe (raw MinGW).

Wann nehmen?​

  • Du nutzt Claude Code und willst 5 Minuten investieren, nicht 5 Stunden
  • Dein Task passt in eine einzelne Session ohne externes Orchestration-Layer
  • Du brauchst keinen Multi-Modell-Vergleich, kein Telegram-Steering, keine Web-UI

3.3 open-ralph-wiggum – die Multi-Agent-CLI mit Rotation​

Repo: Th0rgal/open-ralph-wiggum · Sprache: Bun + TypeScript

Vollständiger Guide: Open Ralph Wiggum

Profil​

  • 5 Agents unterstützt: Claude Code, Codex, Copilot CLI, Cursor Agent, OpenCode
  • --rotation als Killer-Feature: pro Iteration wird ein anderer Agent angesetzt 
    ralph "..." --rotation "claude-code:opus,codex:gpt-5,opencode:gpt-4o"
  • Tasks-Modus: .ralph/ralph-tasks.md, eine Task pro Iteration
  • Live-Steering in zweitem Terminal: --add-context "Hinweis", --status, --list-tasks
  • Status-Dashboard mit Tool-Counts und Struggle-Indicators

Wann nehmen?​

  • Du willst Modelle direkt vergleichen ohne 3 Tools zu starten
  • Du willst eine schlanke, fokussierte CLI ohne Web-UI/Backend-Schwergewicht
  • Du brauchst Live-Steering, willst aber den Loop nicht unterbrechen

3.4 ralphex – Multi-Phase-Reviews und Plan-Pipelines​

Repo: umputun/ralphex · Sprache: Go (73%) + Python/Shell · Stars: 1.1k+

Profil​

ralphex ist die enterprise-iest Variante: 4-Phasen-Pipeline pro Plan.

PhaseWas passiert
1. Task ExecutionMarkdown-Plan mit ### Task N wird sequenziell abgearbeitet, jede Task in frischer Claude-Session, Validation-Commands automatisch nach jeder Task
2. First Review5 parallele Review-Agents prüfen: quality, implementation, testing, simplification, documentation
3. External Review (optional)Externe Tool (Default: Codex) gibt independent zweites Urteil; Claude bewertet die Findings und korrigiert
4. Second ReviewFokussierter Final-Check mit 2 Agents auf kritische/major Issues
Finalize (optional)Rebase, Notifications, Plan-Archivierung

Plan-Format​

# Plan: User Authentication

## Overview
JWT-basierte Auth mit Refresh-Tokens

## Validation Commands
- `pnpm test`
- `pnpm typecheck`

### Task 1: Login-Endpoint
- [ ] POST /login akzeptiert email+password
- [ ] gibt Bearer-Token zurück
- [ ] Tests grün

### Task 2: Refresh-Flow
- [ ] POST /refresh dreht den Token
- [ ] Tests grün

Highlights​

  • Worktree-Isolation (--worktree) für parallele Pläne im selben Repo
  • Web-Dashboard mit SSE-Streaming, Phase-Filter, Multi-Session-Watch
  • Mid-Run-Steering: Ctrl+\ (SIGQUIT) pausiert die Task, du kannst den Plan editieren, Session neu starten
  • Stalemate-Detection: --review-patience bricht ab, wenn N Review-Runden nichts mehr ändern
  • Rate-Limit-Handling: --wait automatisches Retry
  • Notifications: Telegram, Slack, Email, Webhook nach Loop-Ende
  • VCS-Backend: Git-Default, Mercurial via Translation-Skripten
  • Docker-Wrapper: Read-only auf Credentials, RW nur auf Workspace

Wann nehmen?​

  • Du willst Code-Review automatisiert vor dem Merge
  • Du brauchst Plan-Pipelines mit klar getrennten Phasen
  • Dein Team will eine Web-UI zum Monitoring
  • Du willst Heterogenität Claude-implementiert + Codex-reviewt

3.5 ralph-orchestrator – Hat-System, MCP-Stack, Human-in-the-Loop​

Repo: mikeyobrien/ralph-orchestrator · Sprache: Rust (82%) + TS · Stars: 2.8k

Profil​

ralph-orchestrator ist das architektonisch ambitionierteste Tool: ein Rust-Engine mit React-Frontend, MCP-Server, Telegram-Bot und Hat-System.

Hat-System​

Hats sind spezialisierte AI-Personas, die in Sequenz koordinieren:

HatAufgabe
code-assistImplementiert Features
debugFindet/fixt Bugs
researchSammelt Kontext, liest Repos
reviewQuality-Gates
pdd-to-code-assistÜbersetzt PDD-Specs in Implementation

Hats werden über YAML-Configs (ralph.yml, ralph.qa.yml, ralph.bot.yml) definiert.

Stack​

  • Web-Dashboard (Alpha): Rust-RPC-API + React, Ports 3000/5173
  • MCP-Server: workspace-scoped, ein Server pro Repo, deterministische Config-/Task-Persistenz
  • Terminal-UI: in ratatui gebaut
  • RObot (Telegram-Bot): /status, /tasks, /restart für Live-Steering vom Handy

Backends​

Claude Code, Gemini CLI, Kiro, Codex, Amp, Copilot CLI, OpenCode (sieben).

Workflow​

ralph init --backend claude-code
ralph plan "Add OAuth login"          # PDD-Session: Specs + Designs + Plan
ralph run -p specs/oauth.md            # Loop bis fertig
ralph web                              # Dashboard
ralph mcp serve --workspace-root .     # MCP für andere Tools
ralph bot onboard --telegram           # Steering vom Handy

Wann nehmen?​

  • Du willst Problem-Driven Development (PDD): Specs vor Code
  • Du arbeitest mit anderen MCP-Clients und willst Ralph als MCP-Server einbinden
  • Du willst vom Handy steuern (Telegram)
  • Dir gefällt das Hat-Konzept (klare Rollentrennung)

3.6 ralphy – parallele Worktrees + automatische PRs​

Repo: michaelshimeles/ralphy · Sprache: TS (76%) + Bash · Stars: 2.8k

Profil​

ralphy fokussiert auf Parallelität und GitHub-Integration.

ralphy --prd PRD.md --parallel --max-parallel 5 \
       --branch-per-task --create-pr

Was passiert:

  1. ralphy liest die PRD (Markdown / Folder / YAML / JSON / GitHub-Issues)
  2. Spawnt 5 parallele Agents, jeder in eigenem Worktree mit eigenem Branch
  3. Jeder Agent löst seine Task isoliert, läuft Tests
  4. Bei Erfolg: Auto-Merge ins Base-Branch oder Auto-PR über gh
  5. Merge-Konflikte werden vom AI-Agent selbst aufgelöst
  6. Bei Worktree-Problemen: Fallback auf Sandbox-Mode (Symlinks für node_modules/.git/vendor → schnell auch in Monorepos)

Unterstützte Agents​

Claude Code, OpenCode, Cursor, Codex, Qwen-Code, Factory Droid, Copilot, Gemini CLI – acht, mehr als alle anderen.

Highlights​

  • Browser-Automation: --browser für UI-Tests via agent-browser
  • Branch-pro-Task + Auto-PR – ideal für gh-Workflows
  • Sandbox-Mode mit Symlinks – signifikant schneller in großen Repos
  • Aufgabenquellen: MD, MD-Folder, YAML, JSON, GitHub-Issues
  • Webhook-Notifications in .ralphy/config.yaml

Wann nehmen?​

  • Du willst mehrere Tasks gleichzeitig abarbeiten lassen
  • Du willst automatische PRs statt direkter Commits
  • Du arbeitest in einem großen Monorepo (Sandbox-Mode hilft)
  • UI-Tests sollen automatisch laufen

4. Die große Vergleichstabelle​

snarktank/ralphralph-loop (Plugin)open-ralph-wiggumralphexralph-orchestratorralphy
SpracheBashBash-HookBun + TSGoRust + TSTS + Bash
Install-Aufwandminimalnullnpm/bungo install / brewnpm / cargonpm
Agents2 (Amp, Claude)nur Claude Code51 (+ Wrapper)78
Loop-Mechanismusexterner Bash-LoopStop-Hook (in-session)externer Bun-ProcessMulti-Phase-PipelineHat-Sequenzparallele Worktrees
Agent-Rotation––✅––– (parallel)
Multi-Phase-Reviews–––✅ (5 Agents)––
Parallel-Tasks–––✅ Worktrees–✅ explizit
PRD-Formatprd.jsonfreier Promptfreier Prompt + Tasks-ModusMarkdown-PlanYAML / PDDMD/YAML/JSON/Issues
Persistenzprd.json, progress.txt, AGENTS.mdFilesystem + Git.ralph/*.json/.md.ralphex/progress/Workspace + MCPWorktrees + PRs
Web-UI–––✅ SSE✅ Alpha–
MCP-Server––––✅–
Telegram-Steering–––nur Notification✅ RObot–
Browser-Tests–––––✅
Auto-PRs–––––✅
Sandboxing–––Docker-Wrapper–Symlink-Sandbox
HauptzielgruppeBastler, OG-FansClaude-Code-UserModell-VergleicherEnterprise-ReviewerMCP-/PDD-StackMonorepo + GitHub
Stars (Mai 2026)18.7k(Plugin, n/a)–1.1k2.8k2.8k

5. Entscheidungsbaum​

Bist du Claude-Code-User und willst minimalen Aufwand?
└─ JA → ralph-loop-Plugin
└─ NEIN ↓

Willst du verschiedene Modelle pro Iteration vergleichen?
└─ JA → open-ralph-wiggum (--rotation)
└─ NEIN ↓

Brauchst du Multi-Phase-Code-Review automatisiert?
└─ JA → ralphex
└─ NEIN ↓

Willst du parallele Tasks → Auto-PRs?
└─ JA → ralphy (--parallel --create-pr)
└─ NEIN ↓

Willst du PDD-Workflow, MCP-Server, Telegram-Steering?
└─ JA → ralph-orchestrator
└─ NEIN ↓

→ snarktank/ralph (klassisch, 200 Zeilen Bash, größte Community)

6. Geteilte Best-Practices (gilt für ALLE Ralph-Varianten)​

6.1 Setze IMMER ein Iteration-Limit​

ralph "..." --max-iterations 20

Das --completion-promise ist nur ein String-Match. Ohne Iteration-Limit kann ein vergessener Loop stundenlang laufen und Tokens verbrennen.

6.2 Akzeptanzkriterien VERIFIZIERBAR formulieren​

❌ Schlecht: „Bau eine schöne Login-Seite."
✅ Gut:
  1. POST /login → 200 mit Bearer-Token bei korrekten Credentials
  2. POST /login → 401 bei falschen
  3. `pnpm test login.spec.ts` ist grün
  4. Wenn alle drei erfüllt → Output COMPLETE

Ralph dreht sich, bis Tests grün sind. Ohne Tests dreht er sich bis zum Iteration-Limit.

6.3 Story-Sizing​

„If a task is too big, the LLM runs out of context before finishing and produces poor code." — snarktank/ralph

Faustregel: Eine User-Story = passt in ein Context-Window des verwendeten Modells. Konkret:

  • Datenbank-Migration: ja
  • UI-Komponente mit Tests: ja
  • Server-Action: ja
  • „Komplettes E-Commerce-System": nein – als PRD mit 50+ kleinen Stories aufteilen

6.4 JSON-PRDs schlagen Markdown-PRDs​

Bei umfangreichen Feature-Listen reduziert ein strukturiertes JSON-Schema (Liste mit id, title, acceptance: [], passes: false) die Tendenz des Agents, vorhandene Tests umzuschreiben statt sie zu erfüllen. snarktank/ralph macht das per Default mit prd.json.

6.5 Sandboxing ist Pflicht​

Auto-Approve = Agent kann alles, was du in der Shell könntest. Mitigationen:

  • Dediziertes Repo in einer VM oder einem Container
  • ralphex: Docker-Wrapper · ralphy: Symlink-Sandbox · andere: manuell mit Daytona/sandboxed.sh
  • API-Keys via .env, niemals in Prompts

6.6 Persistente Memory pflegen​

Erfolgreichste Implementierungen (snarktank/ralph) lassen den Agent selbst in jeder Iteration AGENTS.md updaten – Patterns, Gotchas, Konventionen. Diese akkumulierende Memory ist Gold wert.

7. Pitfalls​

SymptomUrsacheFix
Loop läuft endlos, ohne Fortschrittkeine verifizierbaren AkzeptanzkriterienTests/Linter als Gate, klares Completion-Promise
Agent schreibt Tests so um, dass sie grün sindweiches AkzeptanzkriteriumJSON-PRD, Tests-als-Spec explizit „nicht ändern" markieren
Token-Kosten explodierenzu großes Modell, zu viele Iterationenkleineres Modell für Routine, --max-iterations strenger
Agent vergisst Patterns aus früheren Iterationenkeine AGENTS.md/progress.txtMemory-File pflegen, im Prompt explizit referenzieren
Auto-Commits pollutieren Historyjede Iteration committetsnarktank: ist Feature; sonst --no-commit + Squash
Stop-Hook-Plugin scheitert auf Windowswsl: Unknown key BugGit-Bash explizit in hooks.json setzen (siehe §3.2)
Mehrere Worktrees crashenBranch-Konflikteralphy hat Conflict-Resolution; sonst Worktree-Modus von ralphex

8. Beispielhafter Stack​

Ein produktiver Setup für 2026:

┌──────────────────────────────────────────────────────────────────┐
│ Tägliches Coden                                                  │
│   └─ Claude Code + ralph-loop-Plugin                             │
│      → kleine, gut definierte Loops während ich was anderes mache│
├──────────────────────────────────────────────────────────────────┤
│ Größere Features                                                 │
│   └─ open-ralph-wiggum mit --rotation                            │
│      → komplexes Refactoring, Modelle gegeneinander testen       │
├──────────────────────────────────────────────────────────────────┤
│ Pre-Merge-Review                                                 │
│   └─ ralphex --review                                            │
│      → 5 Review-Agents auf einen Branch                          │
├──────────────────────────────────────────────────────────────────┤
│ Massen-Tickets                                                   │
│   └─ ralphy --parallel --create-pr aus GitHub-Issues             │
│      → 5 Tickets gleichzeitig zu Draft-PRs                       │
└──────────────────────────────────────────────────────────────────┘

9. Weiterführend​

Quellen & Originale

Implementierungen

Verwandte Themen

Quote

„Failures are predictable and informative. Persistence wins. Operator skill matters." — Ralph-Wiggum-Philosophie in drei Sätzen