Aan de Slag met Ralph Wiggum Part 1: Introductie en Fundamenten

Je staart naar een saaie migratietaak — 200 testbestanden die geconverteerd moeten worden van Jest naar Vitest. De patronen zijn duidelijk. Het werk is mechanisch. Maar het gaat je hele dag kosten.

Of je typt één commando, gaat lunchen en komt terug om het klaar te vinden.

Dat is Ralph Wiggum. En als je het eenmaal hebt gebruikt, vraag je je af hoe je ooit zonder hebt gewerkt.

Wat is Claude Code?

Claude Code is Anthropic's officiële CLI voor Claude — een terminal-gebaseerde AI-codeerassistent die bestanden in je codebase kan lezen, schrijven en bewerken. In tegenstelling tot chatinterfaces werkt Claude Code direct met je lokale bestanden, voert commando's uit en integreert in je ontwikkelworkflow. Voor een volledige introductie, zie Claude Code Mastery Part 1: Getting Started.

Wat is Ralph Wiggum?

Ralph is een Claude Code-plugin die je AI-assistent verandert in een autonome codeeragent. In plaats van het gebruikelijke heen-en-weer — prompt, beoordeel, prompt, beoordeel — geef je Ralph een taak en loop je weg. Het werkt door totdat de klus daadwerkelijk gedaan is.

De filosofie is simpel: Iteratie > Perfectie. Probeer het niet in één keer goed te krijgen bij de eerste prompt. Laat de loop het afhandelen.

Zoals Geoffrey Huntley, de bedenker van de techniek, het verwoordt: "Ralph is een Bash-loop." Dat is letterlijk wat het is — een while true die Claude dezelfde prompt voedt totdat aan de voltooiingscriteria is voldaan.

Dit zijn de mechanismen:

1. Je geeft Claude een taak met duidelijke voltooiingscriteria
2. Claude werkt eraan en probeert af te sluiten wanneer het "klaar" is
3. Een Stop-hook onderschept en controleert: is het echt klaar? (Hooks zijn geautomatiseerde acties die op specifieke momenten in Claude's levenscyclus draaien — zie Mastery Part 3 voor details)
4. Zo niet, dan wordt dezelfde prompt opnieuw ingevoerd
5. Claude ziet zijn vorige werk in de bestanden
6. De loop gaat door tot echte voltooiing

Het belangrijkste inzicht? De prompt verandert nooit — maar de codebase wel. Elke iteratie bouwt voort op de vorige. Claude leest zijn eigen eerdere werk en verbetert het.

Waarom Dit Ertoe Doet

Dit is niet theoretisch. Developers draaien 14 uur durende autonome sessies die complete codebases migreren. Geoffrey Huntley draaide een 3 maanden durende loop die een programmeertaal bouwde. VentureBeat noemde Ralph "de grootste naam in AI op dit moment."

De plugin werd geformaliseerd door Boris Cherny, Anthropic's Head of Claude Code. Het is officieel. Het is productie-klaar. En het verandert hoe serieuze developers werken.

Aan de Slag (5 Minuten)

Stap 1: Installeer de Dependency

Ralph heeft jq nodig voor JSON-verwerking. Installeer het eerst:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows: Gebruik WSL of download het van https://stedolan.github.io/jq/

Stap 2: Installeer de Plugin

Draai binnen Claude Code /plugin om de plugin-ontdekkingsinterface te openen. Zoek naar "ralph" en selecteer ralph-loop uit de officiële plugins.

Of installeer direct met:

/plugin install ralph-loop@claude-plugins-official

Stap 3: Configureer Permissies

Hier gaat het bij de meeste mensen mis: Ralph draait autonoom, wat betekent dat het niet kan stoppen en je vragen "is dit oké?" voor elke bestandswijziging. Als je geen permissies configureert, breekt de loop op het moment dat Claude een permissieprompt tegenkomt.

Optie A: Vooraf goedkeuren in instellingen (aanbevolen)

Voeg de tools die Ralph nodig heeft toe aan je .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(npm:test *)",
      "Bash(npm:run build *)",
      "Bash(git:add *)",
      "Bash(git:commit *)"
    ]
  }
}

Permissie-syntax begrijpen: Het patroon Bash(npm:test *) betekent "sta elk Bash-commando toe dat begint met npm test". De * werkt als wildcard. Dit geeft Ralph toestemming om tests te draaien zonder je elke keer te vragen. Zie Mastery Part 3: Project Configuration voor volledige details over permissiepatronen.

Optie B: Gebruik permissievlaggen

Voor langlopende taken in een sandbox-omgeving kun je permissieprompts volledig omzeilen:

claude --dangerously-skip-permissions
# of
claude --permission-mode acceptEdits

Waarschuwing: Gebruik --dangerously-skip-permissions alleen in sandbox-omgevingen (containers, VM's, wegwerp-cloudinstances). Het geeft Claude volledige toegang tot je bestandssysteem.

Zoals Boris Cherny aangeeft, wil je voor zeer langlopende taken óf --permission-mode=acceptEdits óf --dangerously-skip-permissions in een sandbox zodat Claude niet geblokkeerd staat te wachten op jou.

Optie C: Volledige Sandboxing (Aanbevolen voor Langlopende Taken)

Voor serieus autonoom werk isoleert Claude Code's ingebouwde sandboxing Ralph terwijl het nog steeds de nodige operaties toestaat. Schakel het in door /sandbox te draaien in Claude Code, wat OS-niveau bestands- en netwerkisolatie biedt.

Je kunt ook permissieregels configureren in .claude/settings.json om te bepalen waartoe Ralph toegang heeft:

{
  "permissions": {
    "allow": [
      "WebFetch(domain:registry.npmjs.org)",
      "WebFetch(domain:github.com)"
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(docker:*)",
      "Read(./.env)",
      "Read(~/.ssh/**)"
    ]
  }
}

Pas de allow/deny-lijsten aan voor de behoeften van je project. Zie JeredBlu's gids voor meer configuratievoorbeelden.

Stap 4: Draai Je Eerste Loop

Begin klein. Dit is een veilig eerste experiment:

/ralph-loop "Add JSDoc comments to all exported functions in src/utils.ts. Output <promise>DONE</promise> when complete." --completion-promise "DONE" --max-iterations 10

Kijk hoe het werkt. Bekijk de commits. Krijg een gevoel voor het ritme.

De Twee Parameters Die Ertoe Doen

--max-iterations is je vangnet. Stel het altijd in. De standaard is onbeperkt, wat betekent dat Ralph voor altijd draait als de completion promise nooit triggert.

Begin klein. 10-20 iteraties voor je eerste paar experimenten. Een loop van 50 iteraties op een grote codebase kan $50-100+ aan API-credits kosten.

--completion-promise vertelt Ralph wanneer te stoppen. Het is exacte stringmatching — Claude moet precies deze tekst outputten om voltooiing te signaleren.

/ralph-loop "<je taak>" --max-iterations 30 --completion-promise "TASK COMPLETE"

Plugin vs Bash Loop vs TUI: Welke Gebruik Je

Er zijn drie manieren om Ralph te draaien:

Plugin-Methode (/ralph-loop)

• Draait in een enkel contextvenster
• Makkelijkst op te zetten — nul configuratie
• Goed voor taken onder de 20-30 iteraties

Bash Loop-Methode

• Start een vers contextvenster per iteratie
• Voorkomt contextoverbelasting en hallucinatie
• Vereist handmatige prompt- en bestandsopzet

Ralph TUI (behandeld in Part 3)

• Verse context per iteratie (zoals bash loop)
• Ingebouwde PRD-creatie, taaktracking en monitoringdashboard
• Handelt alle prompt-jongleerwerk en bestandsbeheer voor je af
• Best voor serieuze langlopende builds

Wat is een contextvenster? Het contextvenster is Claude's werkgeheugen — alles wat Claude over je conversatie weet moet hierin passen (~200K tokens). Terwijl je werkt, vult het zich met je prompts, code en Claude's antwoorden. Als het vol zit, begint Claude eerdere details te vergeten. Zie Mastery Part 2: Mental Model voor een diepere uitleg.

Hier is een minimaal bash-loopvoorbeeld:

#!/bin/bash
# loop.sh - Draai dit in plaats van de plugin voor lange taken
for ((i=1; i<=30; i++)); do
  echo "=== Iteratie $i ==="
  result=$(claude -p "$(cat PROMPT.md)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"ALL TASKS COMPLETE"* ]]; then
    echo "Klaar na $i iteraties"
    exit 0
  fi
done

Zoals JeredBlu aangeeft, is de bash-loopmethode "fundamenteel beter voor langlopende taken" omdat elke iteratie vers begint. De plugin draait alles in een enkele context, wat kan leiden tot verminderde prestaties na 30-40 iteraties.

Bekijk echte implementaties: Blader door complete Ralph-setups uit de community:

• snarktank/ralph — Complete ralph.sh, prompt.md en AGENTS.md
• ClaytonFarr/ralph-playbook — PROMPT_plan.md en PROMPT_build.md templates
• frankbria/ralph-claude-code — Implementatie met intelligente exitdetectie

Gebruik je geen Claude Code? Ralph werkt ook met andere tools:

• ralph-wiggum-cursor — Cursor IDE-integratie met tokentracking
• aymenfurter/ralph — VS Code-extensie met visueel bedieningspaneel
• opencode-ralph-wiggum — OpenCode met struggle-detectie

Aanbeveling: Begin met de plugin om de concepten te leren. Gebruik voor productie langlopende taken Ralph TUI — dat geeft je de voordelen van de bash-loopbenadering zonder de handmatige opzet. Zie Part 3 voor de volledige TUI-gids.

Prompts Schrijven Die Werken

Dit is het verschil tussen een prompt die eindeloos rondspint en een die netjes afrondt:

Slechte prompt (vage voltooiing):

Make the code better.

Goede prompt (specifiek en testbaar):

Add comprehensive error handling to src/api/users.ts.

Requirements:
- Wrap all async operations in try/catch
- Return proper HTTP status codes
- Log errors with context
- Add input validation for all endpoints

Run tests after each change. Fix any failures before moving on.

When ALL tests pass, output: <promise>COMPLETE</promise>

De goede prompt heeft:

• Duidelijke scope — specifiek bestand, specifieke wijzigingen
• Testbare criteria — "tests slagen" is binair, niet subjectief
• Ingebouwde kwaliteitspoorten — "los fouten op voordat je verdergaat"
• Expliciet voltooiingssignaal — exacte tekst om te outputten wanneer klaar

Wanneer Ralph Gebruiken (En Wanneer Niet)

Ralph blinkt uit bij:

• Mechanische refactoring — Jest → Vitest, CommonJS → ESM
• Tests toevoegen — "Krijg coverage naar 80% op deze module"
• CRUD-operaties — "Voeg gebruikersbeheereindpunten toe met validatie"
• Documentatie — "Voeg JSDoc toe aan alle publieke functies"
• Migraties — "Update alle imports om padaliassen te gebruiken"

Gebruik Ralph niet voor:

• Esthetische beslissingen — "Maak de UI mooier" is niet testbaar
• Eenmalige bewerkingen — Als het handmatig 30 seconden duurt, doe het dan gewoon
• Productie-debugging — Je hebt context en beoordelingsvermogen nodig, geen iteratie
• Onduidelijke doelen — "Maak het beter" zal eindeloos doordraaien

De vuistregel: Als je een geautomatiseerde test kunt schrijven voor "klaar", kan Ralph het doen. Als voltooiing menselijk oordeel vereist, doe het dan zelf.

De Ralph-Filosofie

The Ralph Playbook documenteert vier kernprincipes die dit laten werken:

1. Iteratie > Perfectie — Probeer het niet in één keer goed te krijgen bij de eerste prompt. Laat de loop verfijnen.
2. Mislukkingen Zijn Data — Als Ralph faalt, leer je hoe je betere prompts schrijft.
3. Operator-Vaardigheid Doet Ertoe — De kwaliteit van je prompts bepaalt Ralph's slagingspercentage.
4. Volharding Wint — De loop handelt retries automatisch af. Jij definieert alleen "klaar."

Het community-mantra: "Beter voorspelbaar falen dan onvoorspelbaar slagen."

Langlopende Loops Monitoren

Wanneer Ralph langere tijd draait, wil je zichtbaarheid. Ralph TUI geeft je een real-time dashboard: iteratietelling, huidige taak, tokengebruik en toetsenbordbediening om te pauzeren of stoppen.

We behandelen monitoring in detail in Part 3: Ralph TUI Monitoring.

Wat Volgt

Je hebt Ralph geïnstalleerd. Je begrijpt de loop. Je weet wanneer je het moet gebruiken en wanneer je dingen handmatig moet doen.

Maar we hebben nog maar het oppervlak aangeraakt.

In Part 2: The Three-Phase Methodology behandelen we de professionele workflow — aparte prompts voor planning en bouwen, spec-bestanden die meerdaagse projecten begeleiden, en de technieken die langlopende autonome builds daadwerkelijk laten werken. Dit is waar Ralph van "nuttige tool" naar "krachtvermeerderer" gaat.

Woordenlijst

Nieuw met Claude Code? Dit zijn de belangrijkste termen die je in deze serie tegenkomt:

Contextvenster — Claude's werkgeheugen. Alles wat Claude over je conversatie weet moet hierin passen (~200K tokens). Meer leren

Backpressure — Geautomatiseerde validatie (tests, lints, typechecks) die slecht werk afwijst en Claude dwingt te itereren tot het correct is

Completion promise — Exacte tekst die Claude moet outputten om taakvoltooiing te signaleren. Ralph gebruikt stringmatching om dit te detecteren

Iteratie — Eén complete denk-doe-observeer-corrigeer-cyclus. Een taak kan meerdere iteraties vergen

Subagent — Gespecialiseerde AI-worker met onafhankelijke context die parallel draait. Meer leren

MCP — Model Context Protocol. Verbindt Claude met externe diensten zoals databases, API's en browserautomatisering. Meer leren

Ultrathink — Trefwoord dat het maximale denkbudget (~32K tokens) toewijst voor complexe redenering. Meer leren