Primeros Pasos con Ralph Wiggum Parte 3: Monitoreo y Visibilidad con Ralph TUI

Ejecutar Ralph Wiggum de forma autónoma es poderoso, pero monitorear bucles ciegos puede sentirse como confiar en un piloto que no puedes ver. Ralph-TUI resuelve el problema de visibilidad dándote un panel en tiempo real de cada iteración, tarea y decisión que tu agente de IA toma.

El Problema de la Visibilidad

Cuando Ralph Wiggum se ejecuta en modo autónomo, opera de forma independiente: lee especificaciones, crea planes, construye funcionalidades, ejecuta tests e itera durante horas o incluso días. Esta autonomía es su fortaleza, pero crea un desafío crítico: no puedes ver qué está pasando sin revisar archivos constantemente.

El bucle podría estar:

• Atascado en un test fallido durante 30 minutos
• Iterando sobre la tarea equivocada por una mala interpretación del plan
• Generando miles de líneas de log que nunca vas a revisar
• Tomando decisiones arquitectónicas que querrías detectar a tiempo

Entra Ralph-TUI: Una interfaz de terminal que proporciona visibilidad en tiempo real del bucle autónomo sin interrumpir la ejecución. Es como añadir una cabina de mando a tu piloto automático.

Por Qué Existe Ralph-TUI

Ralph-TUI fue creado para cerrar la brecha entre "completamente autónomo" y "completamente opaco". Aunque Ralph Wiggum destaca trabajando de forma independiente, los builds de larga duración (más de 3 horas, proyectos de varios días) necesitan observabilidad por tres razones:

1. Eficiencia en depuración: Detecta problemas en tiempo real en vez de descubrirlos después de 100 iteraciones
2. Seguimiento de progreso: Sabe qué tareas están completas, en progreso o pendientes
3. Generación de confianza: Ve el razonamiento y la toma de decisiones del agente a medida que ocurren
4. Sin malabarismos manuales: Automatiza todas las plantillas de prompts, gestión de archivos y seguimiento de iteraciones que configuramos manualmente en la Parte 1 y la Parte 2

Ralph-TUI se ejecuta en paralelo a Ralph Wiggum—no controla ni interrumpe el bucle. Piensa en él como un panel de monitoreo, no como un volante.

Alternativa para usuarios de OpenCode: opencode-ralph-wiggum incluye detección de bloqueo integrada que identifica automáticamente cuando el agente está atascado y lo muestra en tiempo real.

Cuándo Usar Ralph-TUI y Cuándo No

Usa Ralph-TUI para:

• Builds de larga duración (más de 3 horas)
• Proyectos de varios días con más de 20 tareas
• Creación guiada de PRDs (el skill /ralph-tui-prd te guía paso a paso)
• Depuración de bucles problemáticos (cuando Ralph se queda atascado)
• Colaboración en equipo (varias personas monitoreando el progreso)
• Aprender cómo Ralph aborda problemas complejos

Sáltate Ralph-TUI para:

• Builds rápidos de 1-2 tareas (menos de 30 minutos)
• Flujos de trabajo de confianza que has ejecutado docenas de veces
• Plantillas de prompt personalizadas (usa el bucle bash de la Parte 2 si necesitas control detallado)
• Entornos con recursos limitados (Ralph-TUI añade un overhead mínimo, pero algo añade)
• Pipelines de CI/CD (usa logging basado en archivos en su lugar)

Instalación y Configuración

Ralph-TUI requiere Bun como runtime. Instala bun primero si no lo tienes:

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

Reinicia tu terminal (o ejecuta source ~/.zshrc) para cargar bun en tu path.

Luego instala Ralph-TUI de forma global con bun:

bun install -g ralph-tui

¿Por qué bun? Ralph-TUI usa módulos nativos de bun para rendimiento. Instalarlo con npm resultará en un error Cannot find module '@opentui/core-darwin-arm64'.

Después de la instalación, ejecuta el comando de configuración para preparar Ralph TUI en tu proyecto:

ralph-tui setup

El asistente de configuración te permite elegir tu rastreador de issues:

• JSON File Tracker — Rastrea tareas en un archivo local prd.json (la opción más simple, sin dependencias)
• Beads Issue Tracker — Rastrea issues usando el CLI bd, parseado desde .beads/beads.jsonl
• Beads + BV (Smart Mode) — Selección de tareas con reconocimiento de grafos usando bv --robot-triage

¿Qué es Beads? Beads es el rastreador de issues respaldado por git de Steve Yegge, diseñado para agentes de IA de programación. Las tareas se almacenan en .beads/beads.jsonl con IDs basados en hash (como bd-a1b2) que previenen conflictos de merge en flujos de trabajo multi-agente. Soporta tareas jerárquicas (epics → tareas → subtareas) y seguimiento de dependencias mediante bd dep add.

¿Qué es BV? La opción "Smart Mode" usa bv (beads viewer), un motor de triaje con reconocimiento de grafos. En vez de que Claude parsee JSONL y adivine prioridades, bv --robot-triage calcula PageRank, caminos críticos, centralidad de intermediación y detección de ciclos para recomendar de forma determinista la tarea de mayor impacto. El selectionReason en tu plantilla de prompt explica por qué se eligió esa tarea.

También instala tres skills en ~/.claude/skills/ como comandos slash:

• /ralph-tui-prd — Crea documentos de requisitos del producto de forma interactiva
• /ralph-tui-create-json — Convierte un PRD al formato prd.json
• /ralph-tui-create-beads — Convierte un PRD al formato de seguimiento de Beads

¿Qué son los skills? Los skills son módulos de conocimiento especializado que Claude carga automáticamente cuando los invocas mediante comandos slash. Extienden las capacidades de Claude con prompts y flujos de trabajo específicos de un dominio. Consulta Mastery Parte 5: Skills para más detalles sobre cómo crear y usar skills.

Verificación del primer lanzamiento:

ralph-tui --version

Deberías ver la información de versión (0.3.0 o superior).

Creación de PRDs con Ralph TUI

Antes de que Ralph pueda construir de forma autónoma, necesita una especificación clara. El skill /ralph-tui-prd transforma tu idea en bruto en un Documento de Requisitos del Producto estructurado a través de una conversación interactiva.

Paso 1: Describe Tu Funcionalidad

Ejecuta /ralph-tui-prd y describe lo que quieres construir en lenguaje natural:

No necesitas una especificación formal—solo explica tu funcionalidad como se la explicarías a un compañero. Incluye contexto sobre tu configuración existente, usuarios objetivo y cualquier restricción.

Paso 2: Revisa la Vista Previa del PRD

Después de hacer preguntas de clarificación, el skill genera una vista previa del PRD:

Paso 3: Elige el Formato de Salida

El skill te pregunta qué formato quieres—archivo JSON o issues de Beads—y luego convierte el PRD automáticamente. Una vez completado, Ralph TUI muestra la interfaz para ejecutar el bucle autónomo.

Cómo Ralph TUI Gestiona el Contexto

Al igual que el enfoque del bucle bash cubierto en la Parte 2, Ralph TUI inicia una ventana de contexto nueva en cada iteración. Esta es la idea clave que hace posibles los builds autónomos de larga duración.

Por Qué Importa el Contexto Fresco

Los bucles de agentes estándar sufren de acumulación de contexto—cada intento fallido permanece en el historial de conversación. Después de unas cuantas iteraciones, el modelo procesa un largo historial de ruido antes de enfocarse en la tarea actual. Ralph TUI resuelve esto generando una nueva instancia del agente en cada ciclo.

El progreso persiste en archivos y git, no en la ventana de contexto del LLM. Cuando el contexto se llena, obtienes un agente fresco con contexto fresco.

Archivos Clave

Ralph TUI usa estos archivos para mantener el estado entre iteraciones:

• prd.json — Definiciones de tareas y estado
• .ralph-tui/progress.md — Resumen de contexto entre iteraciones
• .ralph-tui-session.json — Estado de sesión para pausar/reanudar
• .ralph-tui/config.toml — Configuración del proyecto
• .ralph-tui/iterations/ — Logs de iteraciones (iteration-{N}-{taskId}.log)

El Ciclo de Ejecución

Cada iteración sigue este patrón:

1. Seleccionar tarea — Elige la tarea incompleta de mayor prioridad del prd.json
2. Construir prompt — Renderiza la plantilla Handlebars con el contexto de la tarea
3. Ejecutar agente — Genera una instancia nueva de Claude con contexto limpio
4. Detectar finalización — Parsea la salida en busca de señales de finalización de tarea
5. Actualizar rastreador — Marca la tarea como completa, registra la iteración, repite el bucle

Esta arquitectura significa que cada elemento del PRD debe ser lo suficientemente pequeño para completarse en una sola ventana de contexto. Si una tarea es demasiado grande, divídela en subtareas.

Análisis Profundo de las Funcionalidades Principales

Ralph-TUI proporciona cinco capacidades principales que transforman cómo interactúas con los bucles autónomos:

1. Visibilidad en Tiempo Real con Controles de Teclado

Observa la salida del agente en vivo mientras Ralph ejecuta. Navega por los logs, retrocede para ver iteraciones anteriores y salta a tareas específicas—todo sin interrumpir el bucle autónomo.

Por qué importa: Los builds largos generan miles de líneas de log. Ralph-TUI filtra el ruido y resalta eventos críticos (tests fallidos, commits, transiciones de tareas) para que puedas enfocarte en lo que importa.

2. Orquestación de Tareas

Ralph-TUI muestra automáticamente:

• Qué tarea se está ejecutando actualmente
• Prioridad de la tarea (basada en IMPLEMENTATION_PLAN.md)
• Tareas completadas vs. pendientes
• Porcentaje estimado de progreso

Esto responde a la pregunta: "¿Dónde estamos en el build?"

3. Persistencia de Sesión (Pausar/Reanudar)

¿Necesitas dejar de monitorear pero mantener Ralph funcionando? Las sesiones de Ralph-TUI persisten. Cierra la terminal, ve a comer, reanuda después—el seguimiento del progreso continúa.

Caso de uso: Inicias un build de 6 horas, monitoreas durante 30 minutos, cierras Ralph-TUI, vuelves más tarde. La sesión muestra todo lo que pasó mientras no estabas.

4. Trazado de Subagentes

Cuando Ralph genera subagentes (para testing, linting o subtareas), Ralph-TUI traza la pila de llamadas. Ve qué subagente está activo, en qué está trabajando y cuándo regresa al bucle principal.

¿Qué son los subagentes? Los subagentes son trabajadores de IA especializados con ventanas de contexto independientes que Claude genera para manejar tareas específicas en paralelo. Pueden ejecutar tests, hacer lint del código o abordar subtareas sin consumir el contexto del agente principal. Consulta Mastery Parte 6: Subagentes para una explicación completa.

Por qué importa: Los builds complejos usan de 5 a 10 subagentes. Sin trazado, pierdes visibilidad de la ejecución anidada.

5. Seguimiento de Contexto Entre Iteraciones

Ralph-TUI mantiene el contexto entre iteraciones. Puedes ver:

• Qué cambió entre la iteración 10 y la iteración 11
• Qué archivos se modificaron en cada iteración
• Resultados de tests a través de las iteraciones (¿el mismo test falló 3 veces?)

Esto convierte un flujo de eventos en una narrativa coherente.

Casos de Uso Comunes

Caso de Uso 1: Builds de Larga Duración (Más de 3 Horas)

Escenario: Migrar un codebase legacy de CommonJS a ESM con más de 200 archivos, actualizando imports, corrigiendo errores de tipos y asegurando que todos los tests pasen.

Flujo de trabajo con Ralph-TUI:

1. Inicias el bucle de Ralph a las 2 PM
2. Lanzas Ralph-TUI en un panel tmux separado
3. Monitoreas durante 30 minutos para asegurarte de que Ralph entiende las specs correctamente
4. Te desconectas de tmux (Ctrl+B, d)
5. Vuelves a las 6 PM mediante tmux attach
6. Revisas el estado en el pie de página: "12 completadas | 1 en progreso | 2 pendientes"
7. Exportas logs y verificas los resultados de los tests

Por qué ayuda Ralph-TUI: Sin él, no tendrías idea de si Ralph se quedó atascado en la tarea 3 o completó todas las tareas exitosamente hasta que inspeccionaras los archivos manualmente.

Caso de Uso 2: Proyectos de Varios Días

Escenario: Construir una arquitectura compleja de microservicios durante 2 días, más de 50 tareas.

Flujo de trabajo con Ralph-TUI:

1. Día 1, 9 AM: Inicias Ralph, monitoreas con Ralph-TUI
2. Día 1, 6 PM: Ralph va por la tarea 23/50. Exportas logs, cierras Ralph-TUI, dejas Ralph corriendo
3. Día 2, 9 AM: Lanzas Ralph-TUI otra vez—la sesión muestra el progreso (tareas 24-38 completadas)
4. Día 2, 12 PM: Ralph termina. Revisas la exportación completa de logs

Por qué ayuda Ralph-TUI: La persistencia de sesión significa que no pierdes visibilidad de lo que pasó durante ejecuciones prolongadas. Los logs muestran cada decisión que Ralph tomó mientras no estabas.

Caso de Uso 3: Integración con CI/CD

Escenario: Ejecutar Ralph en un workflow de GitHub Actions o un servidor remoto para builds automatizados de funcionalidades.

Ralph TUI soporta modo headless para pipelines de CI/CD:

ralph-tui run --headless

Esto ejecuta el agente de forma autónoma sin controles interactivos.

Monitoreo remoto: Puedes monitorear instancias headless desde tu máquina local usando la gestión remota de Ralph TUI:

# En el servidor remoto/CI
ralph-tui run --listen --prd ./prd.json

# En tu máquina local
ralph-tui remote add ci server.example.com:7890 --token <TOKEN>
ralph-tui

El TUI muestra pestañas para instancias locales y remotas con indicadores de estado de conexión. Las características de seguridad incluyen tokens de dos niveles, logging de auditoría y rotación automática de tokens.

Consulta la documentación de Ralph TUI para los detalles completos de configuración remota.

Mejores Prácticas

Siempre Empieza en una Rama Nueva

Antes de lanzar Ralph, crea una rama dedicada para la funcionalidad:

git checkout -b feature/my-ralph-task

Por qué importa:

• Ralph hace commits frecuentes—aislarlos mantiene tu rama principal limpia
• Rollback fácil si algo sale mal (git checkout main && git branch -D feature/my-ralph-task)
• Historial de PR limpio cuando estés listo para hacer merge
• Múltiples ejecuciones de Ralph pueden trabajar en paralelo en diferentes ramas

No ejecutes Ralph en main/master. Si Ralph se queda atascado en un bucle o comete errores arquitectónicos, revertir docenas de commits en tu rama principal es doloroso.

Cuándo Pausar/Reanudar

Pausa (presiona Space) cuando:

• Ves un error y quieres leer los logs con calma
• Estás buscando un evento específico con /
• Quieres copiar y pegar la salida del log

Reanuda (presiona Space de nuevo) cuando:

• Has terminado de analizar
• Quieres ver las actualizaciones en tiempo real otra vez

No pauses indefinidamente—el búfer de logs sigue creciendo en segundo plano. Si pausas por más de 30 minutos, considera exportar los logs y reiniciar Ralph-TUI.

Ajustar Iteraciones Sobre la Marcha

¿Necesitas más iteraciones de las que planeaste originalmente? ¿O quieres terminar antes?

• + — Añade más iteraciones a la ejecución actual
• - — Reduce las iteraciones restantes

Usa + cuando:

• Ralph está progresando bien pero se está quedando sin iteraciones
• Una tarea es más compleja de lo esperado y necesita más ciclos
• Quieres extender una ejecución nocturna sin reiniciar

Usa - cuando:

• Ralph completó el trabajo principal y las tareas restantes son opcionales
• Necesitas liberar recursos para otro build
• El enfoque actual no está funcionando y quieres parar de forma limpia

Esto es mejor que matar el proceso—Ralph termina su iteración actual limpiamente y hace commit del progreso antes de detenerse.

Gestión de Logs

Exporta logs regularmente (cada 1-2 horas para builds largos):

• Presiona e para exportar
• Nombra el archivo de forma descriptiva: ralph-build-iteration-1-to-25.txt

Por qué: Si Ralph se cae después de 6 horas, tendrás los logs hasta tu última exportación. Sin exportaciones, podrías perderlo todo.

Automatización: Usa cron para auto-exportar cada hora:

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

Manejo de Múltiples Sesiones

Ralph-TUI soporta una sesión por proyecto. Si inicias múltiples bucles de Ralph en diferentes directorios:

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

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

Puedes monitorear ambos con instancias separadas de Ralph-TUI:

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

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

Cada Ralph-TUI se conecta a su respectivo bucle de Ralph mediante el contexto del directorio.

Flujo de trabajo con tmux para múltiples sesiones:

# Crear sesión tmux
tmux new -s ralph-monitoring

# Dividir en 4 paneles
Ctrl+B, % (división vertical)
Ctrl+B, " (división horizontal en panel izquierdo)
Ctrl+B, " (división horizontal en panel derecho)

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

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

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

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

Ahora puedes monitorear dos builds autónomos lado a lado.

Monitoreo de Recursos

Ralph-TUI en sí es ligero (~20 MB de memoria, menos del 1% de CPU), pero las sesiones de larga duración pueden acumular logs que consumen espacio en disco.

Verifica el uso de disco:

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

Si ves más de 1 GB, limpia las sesiones antiguas:

rm ~/.ralph-tui/sessions/*.json
rm -rf ~/.ralph-tui/archives/2025-*  # Eliminar archivos de 2025

Limpieza automatizada: Añade a ~/.ralph-tui/config.json:

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

Esto elimina sesiones y archivos de más de 7 días.

Próximos Pasos

Ahora tienes visibilidad completa de los bucles autónomos de Ralph con Ralph-TUI.

En la Parte 4: Patrones Avanzados y Solución de Problemas, cubrimos ingeniería de prompts avanzada, errores comunes, estrategias integrales de solución de problemas y patrones de nivel empresarial que te convertirán en un experto en Ralph.