Aan de slag met Ralph Wiggum Deel 3: Ralph TUI Monitoring & Zichtbaarheid

Ralph Wiggum autonoom draaien is krachtig—maar blinde loops monitoren voelt als vertrouwen op een piloot die je niet kunt zien. Ralph-TUI lost het zichtbaarheidsprobleem op door je een real-time dashboard te geven van elke iteratie, taak en beslissing die je AI-agent maakt.

Het zichtbaarheidsprobleem

Wanneer Ralph Wiggum in autonome modus draait, werkt het zelfstandig—specs lezen, plannen maken, features bouwen, tests draaien en urenlang of zelfs dagenlang itereren. Deze autonomie is zijn kracht, maar het creëert een kritieke uitdaging: je kunt niet zien wat er gebeurt zonder constant bestanden te controleren.

De loop kan:

• 30 minuten vasthangen op een falende test
• Itereren op de verkeerde taak door verkeerde interpretatie van het plan
• Duizenden logregels genereren die je nooit zult bekijken
• Architectuurbeslissingen nemen die je vroeg wilt opmerken

Maak kennis met Ralph-TUI: Een terminalinterface die real-time zichtbaarheid biedt in de autonome loop zonder de uitvoering te onderbreken. Het is alsof je een cockpit toevoegt aan je automatische piloot.

Waarom Ralph-TUI bestaat

Ralph-TUI is gemaakt om de kloof te overbruggen tussen "volledig autonoom" en "volledig ondoorzichtig." Hoewel Ralph Wiggum uitblinkt in zelfstandig werken, hebben langlopende builds (3+ uur, meerdaagse projecten) observability nodig om drie redenen:

1. Efficiënt debuggen: Problemen in real-time opvangen in plaats van ze te ontdekken na 100 iteraties
2. Voortgang bijhouden: Weten welke taken af zijn, bezig zijn of nog wachten
3. Vertrouwen opbouwen: De redenering en besluitvorming van de agent live volgen
4. Geen handmatig gepruts: Automatiseert alle prompttemplates, bestandsbeheer en iteratietracking die we handmatig instelden in Deel 1 en Deel 2

Ralph-TUI draait naast Ralph Wiggum—het bestuurt of onderbreekt de loop niet. Zie het als een monitoringdashboard, niet als een stuur.

Alternatief voor OpenCode-gebruikers: opencode-ralph-wiggum bevat ingebouwde worsteling-detectie die automatisch herkent wanneer de agent vastloopt en dit real-time toont.

Wanneer Ralph-TUI wel en niet gebruiken

Gebruik Ralph-TUI voor:

• Langlopende builds (3+ uur)
• Meerdaagse projecten met 20+ taken
• Begeleide PRD-creatie (de /ralph-tui-prd skill leidt je erdoorheen)
• Problematische loops debuggen (wanneer Ralph vastloopt)
• Teamsamenwerking (meerdere mensen die voortgang monitoren)
• Leren hoe Ralph complexe problemen aanpakt

Sla Ralph-TUI over voor:

• Snelle builds van 1-2 taken (< 30 minuten)
• Vertrouwde workflows die je al tientallen keren hebt gedraaid
• Aangepaste prompttemplates (gebruik de bash-loop uit Deel 2 als je fijnmazige controle nodig hebt)
• Resource-beperkte omgevingen (Ralph-TUI voegt minimale overhead toe, maar toch enige)
• CI/CD-pipelines (gebruik in plaats daarvan bestandsgebaseerde logging)

Installatie & Setup

Ralph-TUI vereist Bun als runtime. Installeer eerst bun als je het nog niet hebt:

curl -fsSL https://bun.sh/install | bash

Herstart je terminal (of voer source ~/.zshrc uit) om bun in je pad te laden.

Installeer Ralph-TUI dan globaal met bun:

bun install -g ralph-tui

Waarom bun? Ralph-TUI gebruikt bun-native modules voor performance. Installeren met npm resulteert in een Cannot find module '@opentui/core-darwin-arm64' fout.

Na installatie voer je het setup-commando uit om Ralph TUI voor je project te configureren:

ralph-tui setup

De setup-wizard laat je kiezen welke issue tracker je wilt gebruiken:

• JSON File Tracker — Taken bijhouden in een lokaal prd.json bestand (eenvoudigste optie, geen afhankelijkheden)
• Beads Issue Tracker — Issues bijhouden met de bd CLI, geparsed uit .beads/beads.jsonl
• Beads + BV (Smart Mode) — Grafisch-bewuste taakselectie met bv --robot-triage

Wat is Beads? Beads is Steve Yegge's git-backed issue tracker ontworpen voor AI coding agents. Taken worden opgeslagen in .beads/beads.jsonl met hash-gebaseerde ID's (zoals bd-a1b2) die merge-conflicten voorkomen in multi-agent workflows. Het ondersteunt hiërarchische taken (epics → taken → subtaken) en dependency tracking via bd dep add.

Wat is BV? De "Smart Mode" optie gebruikt bv (beads viewer)—een grafisch-bewuste triage-engine. In plaats van dat Claude JSONL parst en prioriteiten raadt, berekent bv --robot-triage PageRank, kritieke paden, betweenness centrality en cyclusdetectie om deterministisch de taak met de meeste impact aan te bevelen. De selectionReason in je prompttemplate legt uit waarom die taak is gekozen.

Het installeert ook drie skills naar ~/.claude/skills/ als slash-commando's:

• /ralph-tui-prd — Interactief productvereistendocumenten maken
• /ralph-tui-create-json — PRD converteren naar prd.json formaat
• /ralph-tui-create-beads — PRD converteren naar Beads issue tracking formaat

Wat zijn skills? Skills zijn gespecialiseerde kennismodules die Claude automatisch laadt wanneer je ze aanroept via slash-commando's. Ze breiden Claude's mogelijkheden uit met domeinspecifieke prompts en workflows. Zie Mastery Deel 5: Skills voor details over het maken en gebruiken van skills.

Verificatie na eerste launch:

ralph-tui --version

Je zou versie-informatie moeten zien (0.3.0 of hoger).

PRD's maken met Ralph TUI

Voordat Ralph autonoom kan bouwen, heeft het een duidelijke specificatie nodig. De /ralph-tui-prd skill transformeert je ruwe idee in een gestructureerd Product Requirements Document via een interactief gesprek.

Stap 1: Beschrijf je feature

Voer /ralph-tui-prd uit en beschrijf in gewone taal wat je wilt bouwen:

Je hebt geen formele spec nodig—leg je feature gewoon uit zoals je dat tegen een collega zou doen. Voeg context toe over je bestaande setup, doelgebruikers en eventuele beperkingen.

Stap 2: Bekijk de PRD-preview

Na het stellen van verduidelijkende vragen genereert de skill een PRD-preview:

Stap 3: Kies het outputformaat

De skill vraagt welk formaat je wilt—JSON-bestand of Beads-issues—en converteert de PRD vervolgens automatisch. Na voltooiing toont Ralph TUI de interface voor het draaien van de autonome loop.

Hoe Ralph TUI context beheert

Net als de bash-loop-aanpak die in Deel 2 wordt behandeld, start Ralph TUI elke iteratie een nieuw contextvenster. Dit is het kernidee dat langlopende autonome builds mogelijk maakt.

Waarom een nieuw context belangrijk is

Standaard agent-loops lijden onder contextaccumulatie—elke mislukte poging blijft in de gespreksgeschiedenis staan. Na een paar iteraties verwerkt het model een lange geschiedenis van ruis voordat het zich op de huidige taak richt. Ralph TUI lost dit op door elke cyclus een nieuwe agent-instantie te spawnen.

Voortgang wordt bewaard in bestanden en git, niet in het contextvenster van de LLM. Wanneer de context vol raakt, krijg je een nieuwe agent met een schoon context.

Belangrijke bestanden

Ralph TUI gebruikt deze bestanden om de status tussen iteraties te behouden:

• prd.json — Taakdefinities en status
• .ralph-tui/progress.md — Samenvatting van cross-iteratie context
• .ralph-tui-session.json — Sessiestatus voor pauzeren/hervatten
• .ralph-tui/config.toml — Projectconfiguratie
• .ralph-tui/iterations/ — Iteratielogs (iteration-{N}-{taskId}.log)

De uitvoeringscyclus

Elke iteratie volgt dit patroon:

1. Taak selecteren — De hoogste prioriteit incomplete taak uit prd.json kiezen
2. Prompt opbouwen — Handlebars-template renderen met taakcontext
3. Agent uitvoeren — Nieuwe Claude-instantie spawnen met schoon context
4. Voltooiing detecteren — Output parsen op taakvoltooiingssignalen
5. Tracker bijwerken — Taak als voltooid markeren, iteratie loggen, loopen

Deze architectuur betekent dat elk PRD-item klein genoeg moet zijn om in één contextvenster af te ronden. Als een taak te groot is, splits je deze op in subtaken.

Kernfuncties uitgelicht

Ralph-TUI biedt vijf kernmogelijkheden die de manier waarop je met autonome loops werkt transformeren:

1. Real-time zichtbaarheid met toetsenbordbesturing

Bekijk agent-output live terwijl Ralph uitvoert. Navigeer door logs, scroll terug naar eerdere iteraties en spring naar specifieke taken—allemaal zonder de autonome loop te onderbreken.

Waarom dit belangrijk is: Langlopende builds genereren duizenden logregels. Ralph-TUI filtert ruis en markeert kritieke gebeurtenissen (testfouten, commits, taakovergangen) zodat je je kunt concentreren op wat ertoe doet.

2. Taakorchestratie

Ralph-TUI toont automatisch:

• Welke taak momenteel wordt uitgevoerd
• Taakprioriteit (gebaseerd op IMPLEMENTATION_PLAN.md)
• Voltooide versus openstaande taken
• Geschat voortgangspercentage

Dit beantwoordt de vraag: "Waar staan we in de build?"

3. Sessiepersistentie (Pauzeren/Hervatten)

Moet je stoppen met monitoren maar Ralph laten draaien? Ralph-TUI-sessies blijven bewaard. Sluit de terminal, ga lunchen, hervat later—voortgangsregistratie gaat door.

Gebruiksscenario: Start een 6 uur durende build, monitor 30 minuten, sluit Ralph-TUI, check later weer. De sessie toont alles wat er is gebeurd terwijl je weg was.

4. Subagent-tracing

Wanneer Ralph subagents spawnt (voor testen, linting of subtaken), traceert Ralph-TUI de call stack. Zie welke subagent actief is, waaraan die werkt, en wanneer die terugkeert naar de hoofdloop.

Wat zijn subagents? Subagents zijn gespecialiseerde AI-workers met onafhankelijke contextvensters die Claude spawnt om specifieke taken parallel af te handelen. Ze kunnen tests draaien, code linten of subtaken oppakken zonder het context van de hoofdagent te gebruiken. Zie Mastery Deel 6: Subagents voor een volledige uitleg.

Waarom dit belangrijk is: Complexe builds gebruiken 5-10 subagents. Zonder tracing verlies je zicht op geneste uitvoering.

5. Cross-iteratie contexttracking

Ralph-TUI behoudt context tussen iteraties. Bekijk:

• Wat er veranderde tussen iteratie 10 en iteratie 11
• Welke bestanden in elke iteratie zijn gewijzigd
• Testresultaten over iteraties heen (faalde dezelfde test 3 keer?)

Dit verandert een stroom gebeurtenissen in een samenhangend verhaal.

Veelvoorkomende use cases

Use case 1: Langlopende builds (3+ uur)

Scenario: Een legacy codebase migreren van CommonJS naar ESM met 200+ bestanden, imports bijwerken, typefouten fixen en ervoor zorgen dat alle tests slagen.

Ralph-TUI workflow:

1. Start de Ralph-loop om 14:00
2. Start Ralph-TUI in een apart tmux-paneel
3. Monitor 30 minuten om te controleren of Ralph de specs goed begrijpt
4. Ontkoppel van tmux (Ctrl+B, d)
5. Check om 18:00 opnieuw via tmux attach
6. Bekijk de footerstatus: "12 voltooid | 1 bezig | 2 openstaand"
7. Exporteer logs en verifieer testresultaten

Waarom Ralph-TUI helpt: Zonder zou je geen idee hebben of Ralph vastliep bij taak 3 of alle taken succesvol afrondde, totdat je handmatig bestanden inspecteert.

Use case 2: Meerdaagse projecten

Scenario: Een complexe microservices-architectuur bouwen over 2 dagen, 50+ taken.

Ralph-TUI workflow:

1. Dag 1, 09:00: Start Ralph, monitor met Ralph-TUI
2. Dag 1, 18:00: Ralph is bij taak 23/50. Exporteer logs, sluit Ralph-TUI, laat Ralph draaien
3. Dag 2, 09:00: Start Ralph-TUI opnieuw—de sessie toont voortgang (taken 24-38 voltooid)
4. Dag 2, 12:00: Ralph is klaar. Bekijk de volledige log-export

Waarom Ralph-TUI helpt: Sessiepersistentie betekent dat je geen zicht verliest op wat er tijdens lange runs is gebeurd. Logs tonen elke beslissing die Ralph nam terwijl je weg was.

Use case 3: CI/CD-integratie

Scenario: Ralph draaien in een GitHub Actions workflow of op een remote server voor geautomatiseerde feature-builds.

Ralph TUI ondersteunt headless modus voor CI/CD-pipelines:

ralph-tui run --headless

Dit voert de agent autonoom uit zonder interactieve besturing.

Remote monitoring: Je kunt headless instanties monitoren vanaf je lokale machine met Ralph TUI's remote management:

# Op de remote/CI-server
ralph-tui run --listen --prd ./prd.json

# Op je lokale machine
ralph-tui remote add ci server.example.com:7890 --token <TOKEN>
ralph-tui

De TUI toont tabbladen voor lokale en remote instanties met verbindingsstatusindicatoren. Beveiligingsfuncties omvatten twee-laags tokens, auditlogging en automatische tokenrotatie.

Zie de Ralph TUI-documentatie voor volledige remote setup-details.

Best practices

Begin altijd op een nieuwe branch

Maak voordat je Ralph start een dedicated feature-branch aan:

git checkout -b feature/my-ralph-task

Waarom dit belangrijk is:

• Ralph maakt regelmatig commits—isolatie houdt je main-branch schoon
• Eenvoudige rollback als er iets misgaat (git checkout main && git branch -D feature/my-ralph-task)
• Schone PR-geschiedenis wanneer je klaar bent om te mergen
• Meerdere Ralph-runs kunnen parallel op verschillende branches werken

Draai Ralph niet op main/master. Als Ralph vastloopt in een loop of architectuurfouten maakt, is het terugdraaien van tientallen commits op je primaire branch pijnlijk.

Wanneer pauzeren/hervatten

Pauzeer (druk op Space) wanneer:

• Je een fout ziet en de logs rustig wilt lezen
• Je een specifieke gebeurtenis zoekt met /
• Je log-output wilt kopiëren

Hervat (druk opnieuw op Space) wanneer:

• Je klaar bent met analyseren
• Je weer real-time updates wilt zien

Pauzeer niet onbeperkt—de logbuffer groeit door op de achtergrond. Als je langer dan 30 minuten pauzeert, overweeg dan logs te exporteren en Ralph-TUI opnieuw te starten.

Iteraties on-the-fly aanpassen

Meer iteraties nodig dan je oorspronkelijk had gepland? Of wil je eerder stoppen?

• + — Voeg meer iteraties toe aan de huidige run
• - — Verminder het aantal resterende iteraties

Gebruik + wanneer:

• Ralph goede voortgang boekt maar weinig iteraties overheeft
• Een taak complexer is dan verwacht en meer cycli nodig heeft
• Je een nachtelijke run wilt verlengen zonder opnieuw te starten

Gebruik - wanneer:

• Ralph het kernwerk heeft afgerond en resterende taken optioneel zijn
• Je resources wilt vrijmaken voor een andere build
• De huidige aanpak niet werkt en je netjes wilt stoppen

Dit is beter dan het proces killen—Ralph rondt zijn huidige iteratie netjes af en commit de voortgang voordat het stopt.

Logbeheer

Exporteer logs regelmatig (elke 1-2 uur bij langlopende builds):

• Druk op e om te exporteren
• Geef het bestand een beschrijvende naam: ralph-build-iteration-1-to-25.txt

Waarom: Als Ralph crasht na 6 uur, heb je logs tot aan je laatste export. Zonder exports verlies je mogelijk alles.

Automatisering: Gebruik cron om elk uur automatisch te exporteren:

0 * * * * cd /path/to/project && ralph-tui export --output logs/ralph-$(date +\%Y-\%m-\%d-\%H-\%M).txt

Multi-sessie beheer

Ralph-TUI ondersteunt één sessie per project. Als je meerdere Ralph-loops start in verschillende mappen:

# Terminal 1
cd /projects/api-v1 && ralph loop PROMPT_plan.md

# Terminal 2
cd /projects/api-v2 && ralph loop PROMPT_plan.md

Kun je beide monitoren met aparte Ralph-TUI-instanties:

# Ralph-TUI 1
cd /projects/api-v1 && ralph-tui run

# Ralph-TUI 2
cd /projects/api-v2 && ralph-tui run

Elke Ralph-TUI verbindt met zijn bijbehorende Ralph-loop via de mapcontext.

Tmux-workflow voor multi-sessie:

# Maak een tmux-sessie aan
tmux new -s ralph-monitoring

# Splits in 4 panelen
Ctrl+B, % (verticale split)
Ctrl+B, " (horizontale split in linker paneel)
Ctrl+B, " (horizontale split in rechter paneel)

# Paneel 1: Ralph loop 1
cd /projects/api-v1 && ralph loop PROMPT_plan.md

# Paneel 2: Ralph-TUI 1
cd /projects/api-v1 && ralph-tui run

# Paneel 3: Ralph loop 2
cd /projects/api-v2 && ralph loop PROMPT_plan.md

# Paneel 4: Ralph-TUI 2
cd /projects/api-v2 && ralph-tui run

Nu kun je twee autonome builds naast elkaar monitoren.

Resource monitoring

Ralph-TUI zelf is lichtgewicht (~20 MB geheugen, minder dan 1% CPU), maar langlopende sessies kunnen logs ophopen die schijfruimte verbruiken.

Controleer schijfgebruik:

du -sh ~/.ralph-tui/sessions ~/.ralph-tui/archives

Als je meer dan 1 GB ziet, ruim dan oude sessies op:

rm ~/.ralph-tui/sessions/*.json
rm -rf ~/.ralph-tui/archives/2025-*  # Verwijder archieven uit 2025

Geautomatiseerd opruimen: Voeg toe aan ~/.ralph-tui/config.json:

{
  "cleanup": {
    "enabled": true,
    "maxAge": 7
  }
}

Dit verwijdert sessies en archieven ouder dan 7 dagen.

Wat volgt

Je hebt nu volledig zicht op Ralph's autonome loops met Ralph-TUI.

In Deel 4: Geavanceerde patronen & Probleemoplossing behandelen we geavanceerde prompt engineering, veelvoorkomende valkuilen, uitgebreide probleemoplossingsstrategieën en enterprise-grade patronen die je tot een Ralph-expert maken.