Débuter avec Ralph Wiggum Partie 3 : Monitoring et visibilité avec Ralph TUI

Faire tourner Ralph Wiggum en mode autonome, c'est puissant — mais surveiller des boucles à l'aveugle, c'est comme faire confiance à un pilote que tu ne vois pas. Ralph-TUI résout ce problème de visibilité en te donnant un tableau de bord temps réel sur chaque itération, tâche et décision prise par ton agent IA.

Le problème de visibilité

Quand Ralph Wiggum tourne en mode autonome, il opère de manière indépendante — il lit les specs, crée des plans, développe des fonctionnalités, lance des tests et itère pendant des heures, voire des jours. Cette autonomie est sa force, mais elle crée un défi critique : tu ne peux pas voir ce qui se passe sans vérifier constamment les fichiers.

La boucle pourrait être :

• Bloquée sur un test en échec depuis 30 minutes
• En train d'itérer sur la mauvaise tâche à cause d'une mauvaise interprétation du plan
• En train de générer des milliers de lignes de log que tu ne reliras jamais
• En train de prendre des décisions architecturales que tu voudrais intercepter tôt

Voici Ralph-TUI : une interface terminal qui offre une visibilité en temps réel sur la boucle autonome sans interrompre l'exécution. C'est comme ajouter un cockpit à ton pilote automatique.

Pourquoi Ralph-TUI existe

Ralph-TUI a été créé pour combler le fossé entre « totalement autonome » et « complètement opaque ». Bien que Ralph Wiggum excelle à travailler de manière indépendante, les builds de longue durée (3+ heures, projets sur plusieurs jours) nécessitent de l'observabilité pour trois raisons :

1. Efficacité du débogage : repérer les problèmes en temps réel au lieu de les découvrir après 100 itérations
2. Suivi de progression : savoir quelles tâches sont terminées, en cours ou en attente
3. Gagner en confiance : voir le raisonnement et la prise de décision de l'agent en direct
4. Plus de jonglage manuel : automatise tous les templates de prompt, la gestion des fichiers et le suivi des itérations qu'on avait configurés manuellement dans la Partie 1 et la Partie 2

Ralph-TUI tourne en parallèle de Ralph Wiggum — il ne contrôle ni n'interrompt la boucle. Pense-le comme un tableau de bord de monitoring, pas un volant.

Alternative pour les utilisateurs d'OpenCode : opencode-ralph-wiggum inclut une détection de blocage intégrée qui identifie automatiquement quand l'agent est coincé et le signale en temps réel.

Quand utiliser Ralph-TUI vs. quand s'en passer

Utilise Ralph-TUI pour :

• Les builds de longue durée (3+ heures)
• Les projets sur plusieurs jours avec 20+ tâches
• La création guidée de PRD (le skill /ralph-tui-prd te guide pas à pas)
• Le débogage de boucles problématiques (quand Ralph est bloqué)
• La collaboration en équipe (plusieurs personnes surveillent la progression)
• Comprendre comment Ralph aborde les problèmes complexes

Passe-toi de Ralph-TUI pour :

• Les builds rapides à 1-2 tâches (< 30 minutes)
• Les workflows de confiance que tu as déjà lancés des dizaines de fois
• Les templates de prompt personnalisés (utilise la boucle bash de la Partie 2 si tu as besoin d'un contrôle fin)
• Les environnements limités en ressources (Ralph-TUI ajoute un overhead minimal, mais quand même)
• Les pipelines CI/CD (utilise plutôt le logging par fichiers)

Installation & configuration

Ralph-TUI nécessite Bun comme runtime. Installe d'abord bun si tu ne l'as pas :

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

Redémarre ton terminal (ou lance source ~/.zshrc) pour charger bun dans ton path.

Ensuite, installe Ralph-TUI globalement avec bun :

bun install -g ralph-tui

Pourquoi bun ? Ralph-TUI utilise des modules natifs bun pour la performance. L'installer avec npm provoquera une erreur Cannot find module '@opentui/core-darwin-arm64'.

Après l'installation, lance la commande setup pour configurer Ralph TUI pour ton projet :

ralph-tui setup

L'assistant de configuration te permet de choisir ton tracker d'issues :

• JSON File Tracker — Suivi des tâches dans un fichier local prd.json (option la plus simple, aucune dépendance)
• Beads Issue Tracker — Suivi des issues via le CLI bd, parsé depuis .beads/beads.jsonl
• Beads + BV (Smart Mode) — Sélection de tâches basée sur un graphe via bv --robot-triage

C'est quoi Beads ? Beads est le tracker d'issues basé sur git de Steve Yegge, conçu pour les agents de code IA. Les tâches sont stockées dans .beads/beads.jsonl avec des IDs basés sur des hashes (comme bd-a1b2) qui évitent les conflits de merge dans les workflows multi-agents. Il supporte les tâches hiérarchiques (epics → tâches → sous-tâches) et le suivi des dépendances via bd dep add.

C'est quoi BV ? L'option « Smart Mode » utilise bv (beads viewer) — un moteur de triage basé sur un graphe. Au lieu que Claude parse du JSONL et devine les priorités, bv --robot-triage calcule le PageRank, les chemins critiques, la centralité d'intermédiarité et la détection de cycles pour recommander de manière déterministe la tâche à plus fort impact. Le selectionReason dans ton template de prompt explique pourquoi cette tâche a été choisie.

Il installe aussi trois skills dans ~/.claude/skills/ comme commandes slash :

• /ralph-tui-prd — Créer des documents d'exigences produit de manière interactive
• /ralph-tui-create-json — Convertir un PRD au format prd.json
• /ralph-tui-create-beads — Convertir un PRD au format Beads issue tracking

C'est quoi les skills ? Les skills sont des modules de connaissances spécialisées que Claude charge automatiquement quand tu les invoques via des commandes slash. Ils étendent les capacités de Claude avec des prompts et workflows spécifiques à un domaine. Consulte Mastery Partie 5 : Skills pour les détails sur la création et l'utilisation des skills.

Vérification du premier lancement :

ralph-tui --version

Tu devrais voir les informations de version (0.3.0 ou plus).

Créer des PRDs avec Ralph TUI

Avant que Ralph puisse construire de manière autonome, il a besoin d'une spécification claire. Le skill /ralph-tui-prd transforme ton idée brute en un Document d'Exigences Produit structuré via une conversation interactive.

Étape 1 : Décris ta fonctionnalité

Lance /ralph-tui-prd et décris ce que tu veux construire en langage courant :

Tu n'as pas besoin d'une spec formelle — explique juste ta fonctionnalité comme tu le ferais à un collègue. Inclus le contexte sur ta config existante, les utilisateurs cibles et les contraintes éventuelles.

Étape 2 : Revois l'aperçu du PRD

Après avoir posé des questions de clarification, le skill génère un aperçu du PRD :

Étape 3 : Choisis le format de sortie

Le skill te demande quel format tu veux — fichier JSON ou issues Beads — puis convertit automatiquement le PRD. Une fois terminé, Ralph TUI affiche l'interface pour lancer la boucle autonome.

Comment Ralph TUI gère le contexte

Comme l'approche par boucle bash couverte dans la Partie 2, Ralph TUI démarre une fenêtre de contexte fraîche à chaque itération. C'est l'insight fondamental qui rend les builds autonomes de longue durée possibles.

Pourquoi un contexte frais est important

Les boucles d'agents classiques souffrent de l'accumulation de contexte — chaque tentative échouée reste dans l'historique de conversation. Après quelques itérations, le modèle traite un long historique de bruit avant de se concentrer sur la tâche en cours. Ralph TUI résout ça en créant une nouvelle instance d'agent à chaque cycle.

La progression persiste dans les fichiers et git, pas dans la fenêtre de contexte du LLM. Quand le contexte se remplit, tu obtiens un agent frais avec un contexte frais.

Fichiers clés

Ralph TUI utilise ces fichiers pour maintenir l'état entre les itérations :

• prd.json — Définitions et statuts des tâches
• .ralph-tui/progress.md — Résumé du contexte inter-itérations
• .ralph-tui-session.json — État de session pour pause/reprise
• .ralph-tui/config.toml — Configuration du projet
• .ralph-tui/iterations/ — Logs d'itération (iteration-{N}-{taskId}.log)

Le cycle d'exécution

Chaque itération suit ce schéma :

1. Sélection de tâche — Choisir la tâche incomplète de plus haute priorité dans prd.json
2. Construction du prompt — Rendre le template Handlebars avec le contexte de la tâche
3. Exécution de l'agent — Lancer une instance Claude fraîche avec un contexte propre
4. Détection de complétion — Parser la sortie pour détecter les signaux de complétion de tâche
5. Mise à jour du tracker — Marquer la tâche comme terminée, logger l'itération, boucler

Cette architecture implique que chaque item du PRD doit être assez petit pour être complété en une seule fenêtre de contexte. Si une tâche est trop grande, découpe-la en sous-tâches.

Plongée dans les fonctionnalités principales

Ralph-TUI offre cinq fonctionnalités clés qui transforment ta façon d'interagir avec les boucles autonomes :

1. Visibilité en temps réel avec contrôles clavier

Regarde la sortie de l'agent en direct pendant que Ralph s'exécute. Navigue dans les logs, remonte pour voir les itérations précédentes et saute directement à des tâches spécifiques — le tout sans interrompre la boucle autonome.

Pourquoi c'est important : Les builds longs génèrent des milliers de lignes de log. Ralph-TUI filtre le bruit et met en évidence les événements critiques (échecs de tests, commits, transitions de tâches) pour que tu puisses te concentrer sur l'essentiel.

2. Orchestration des tâches

Ralph-TUI affiche automatiquement :

• Quelle tâche est en cours d'exécution
• La priorité de la tâche (basée sur IMPLEMENTATION_PLAN.md)
• Les tâches terminées vs. en attente
• Le pourcentage de progression estimé

Ça répond à la question : « Où en est-on dans le build ? »

3. Persistance de session (Pause/Reprise)

Besoin d'arrêter le monitoring mais de garder Ralph en marche ? Les sessions Ralph-TUI persistent. Ferme le terminal, va déjeuner, reprends plus tard — le suivi de progression continue.

Cas d'usage : Lance un build de 6 heures, surveille pendant 30 minutes, ferme Ralph-TUI, reviens plus tard. La session montre tout ce qui s'est passé pendant ton absence.

4. Traçage des sous-agents

Quand Ralph lance des sous-agents (pour les tests, le linting ou les sous-tâches), Ralph-TUI trace la pile d'appels. Vois quel sous-agent est actif, sur quoi il travaille et quand il retourne à la boucle principale.

C'est quoi les sous-agents ? Les sous-agents sont des workers IA spécialisés avec des fenêtres de contexte indépendantes que Claude lance pour gérer des tâches spécifiques en parallèle. Ils peuvent exécuter des tests, linter du code ou traiter des sous-tâches sans consommer le contexte de l'agent principal. Consulte Mastery Partie 6 : Sous-agents pour une explication complète.

Pourquoi c'est important : Les builds complexes utilisent 5 à 10 sous-agents. Sans traçage, tu perds la visibilité sur l'exécution imbriquée.

5. Suivi du contexte inter-itérations

Ralph-TUI maintient le contexte entre les itérations. Tu peux voir :

• Ce qui a changé entre l'itération 10 et l'itération 11
• Quels fichiers ont été modifiés à chaque itération
• Les résultats de tests à travers les itérations (est-ce que le même test a échoué 3 fois ?)

Ça transforme un flux d'événements en un récit cohérent.

Cas d'usage courants

Cas 1 : Builds de longue durée (3+ heures)

Scénario : Migration d'un codebase legacy de CommonJS vers ESM avec 200+ fichiers, mise à jour des imports, correction des erreurs de type et vérification que tous les tests passent.

Workflow Ralph-TUI :

1. Lance la boucle Ralph à 14h
2. Lance Ralph-TUI dans un pane tmux séparé
3. Surveille pendant 30 minutes pour vérifier que Ralph comprend bien les specs
4. Détache-toi de tmux (Ctrl+B, d)
5. Reviens à 18h via tmux attach
6. Vérifie le statut en footer : « 12 terminées | 1 en cours | 2 en attente »
7. Exporte les logs et vérifie les résultats de tests

Pourquoi Ralph-TUI aide : Sans lui, tu n'aurais aucune idée si Ralph est bloqué à la tâche 3 ou s'il a terminé toutes les tâches avec succès avant d'inspecter manuellement les fichiers.

Cas 2 : Projets sur plusieurs jours

Scénario : Construction d'une architecture microservices complexe sur 2 jours, 50+ tâches.

Workflow Ralph-TUI :

1. Jour 1, 9h : Lance Ralph, surveille avec Ralph-TUI
2. Jour 1, 18h : Ralph en est à la tâche 23/50. Exporte les logs, ferme Ralph-TUI, laisse Ralph tourner
3. Jour 2, 9h : Relance Ralph-TUI — la session affiche la progression (tâches 24-38 terminées)
4. Jour 2, 12h : Ralph a terminé. Revois l'export complet des logs

Pourquoi Ralph-TUI aide : La persistance de session signifie que tu ne perds pas la visibilité sur ce qui s'est passé pendant les longues exécutions. Les logs montrent chaque décision que Ralph a prise pendant ton absence.

Cas 3 : Intégration CI/CD

Scénario : Faire tourner Ralph dans un workflow GitHub Actions ou un serveur distant pour des builds automatisés de fonctionnalités.

Ralph TUI supporte le mode headless pour les pipelines CI/CD :

ralph-tui run --headless

Ceci exécute l'agent de manière autonome sans contrôles interactifs.

Monitoring distant : Tu peux surveiller des instances headless depuis ta machine locale grâce à la gestion distante de Ralph TUI :

# Sur le serveur distant/CI
ralph-tui run --listen --prd ./prd.json

# Sur ta machine locale
ralph-tui remote add ci server.example.com:7890 --token <TOKEN>
ralph-tui

Le TUI affiche des onglets pour les instances locales et distantes avec des indicateurs de statut de connexion. Les fonctionnalités de sécurité incluent des tokens à deux niveaux, un journal d'audit et une rotation automatique des tokens.

Consulte la documentation de Ralph TUI pour les détails complets de la configuration distante.

Bonnes pratiques

Commence toujours sur une branche fraîche

Avant de lancer Ralph, crée une branche feature dédiée :

git checkout -b feature/my-ralph-task

Pourquoi c'est important :

• Ralph fait des commits fréquents — les isoler garde ta branche principale propre
• Rollback facile si quelque chose tourne mal (git checkout main && git branch -D feature/my-ralph-task)
• Historique de PR propre quand tu es prêt à merger
• Plusieurs runs de Ralph peuvent travailler en parallèle sur des branches différentes

Ne lance pas Ralph sur main/master. Si Ralph se retrouve coincé dans une boucle ou fait des erreurs architecturales, reverter des dizaines de commits sur ta branche principale est pénible.

Quand mettre en pause / reprendre

Mets en pause (appuie sur Espace) quand :

• Tu vois une erreur et tu veux lire les logs attentivement
• Tu cherches un événement spécifique avec /
• Tu veux copier-coller une sortie de log

Reprends (appuie encore sur Espace) quand :

• Tu as fini d'analyser
• Tu veux revoir les mises à jour en temps réel

Ne mets pas en pause indéfiniment — le buffer de logs continue de grossir en arrière-plan. Si tu mets en pause pendant plus de 30 minutes, envisage d'exporter les logs et de redémarrer Ralph-TUI.

Ajuster les itérations à la volée

Besoin de plus d'itérations que prévu initialement ? Ou tu veux terminer plus tôt ?

• + — Ajouter des itérations au run en cours
• - — Réduire les itérations restantes

Utilise + quand :

• Ralph progresse bien mais manque d'itérations
• Une tâche est plus complexe que prévu et nécessite plus de cycles
• Tu veux prolonger un run de nuit sans redémarrer

Utilise - quand :

• Ralph a terminé le travail principal et les tâches restantes sont optionnelles
• Tu as besoin de libérer des ressources pour un autre build
• L'approche actuelle ne fonctionne pas et tu veux arrêter proprement

C'est mieux que de tuer le processus — Ralph termine proprement son itération en cours et commit la progression avant de s'arrêter.

Gestion des logs

Exporte les logs régulièrement (toutes les 1-2 heures pour les builds longs) :

• Appuie sur e pour exporter
• Nomme le fichier de manière descriptive : ralph-build-iteration-1-to-25.txt

Pourquoi : Si Ralph plante après 6 heures, tu auras les logs jusqu'à ta dernière exportation. Sans export, tu pourrais tout perdre.

Automatisation : Utilise cron pour exporter automatiquement toutes les heures :

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

Gestion multi-sessions

Ralph-TUI supporte une session par projet. Si tu lances plusieurs boucles Ralph dans des répertoires différents :

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

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

Tu peux surveiller les deux avec des instances Ralph-TUI séparées :

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

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

Chaque Ralph-TUI se connecte à sa boucle Ralph respective via le contexte du répertoire.

Workflow tmux pour le multi-session :

# Créer une session tmux
tmux new -s ralph-monitoring

# Découper en 4 panes
Ctrl+B, % (split vertical)
Ctrl+B, " (split horizontal dans le pane gauche)
Ctrl+B, " (split horizontal dans le pane droit)

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

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

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

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

Tu peux maintenant surveiller deux builds autonomes côte à côte.

Monitoring des ressources

Ralph-TUI en lui-même est léger (~20 Mo de mémoire, moins de 1% CPU), mais les sessions longues peuvent accumuler des logs qui consomment de l'espace disque.

Vérifie l'utilisation disque :

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

Si tu vois plus de 1 Go, nettoie les anciennes sessions :

rm ~/.ralph-tui/sessions/*.json
rm -rf ~/.ralph-tui/archives/2025-*  # Supprimer les archives de 2025

Nettoyage automatisé : Ajoute à ~/.ralph-tui/config.json :

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

Ceci supprime les sessions et archives de plus de 7 jours.

La suite

Tu as maintenant une visibilité complète sur les boucles autonomes de Ralph avec Ralph-TUI.

Dans la Partie 4 : Patterns avancés & dépannage, on couvre l'ingénierie de prompts avancée, les pièges courants, les stratégies de dépannage complètes et les patterns enterprise-grade qui feront de toi un expert Ralph.