Volver al blog

Como monitorear multiples agentes Claude Code trabajando en paralelo

Como monitorear multiples agentes Claude Code trabajando en paralelo

Lanzaste seis agentes Claude Code en paneles de tmux. Cada uno reclamo una tarea. Todos estan produciendo output, desplazandose mas rapido de lo que puedes leer. Uno acaba de hacer un commit. Otro esta ejecutando tests. Un tercero lleva sospechosamente callado 20 minutos.

No tienes idea de que esta pasando realmente.

Este es el problema central de los flujos de trabajo con agentes en paralelo. Los agentes en si son productivos. Claude Code puede reclamar trabajo, escribir codigo, ejecutar tests e informar sobre la finalizacion a traves de comandos estructurados. Pero el humano que supervisa seis o diez de estos agentes no tiene una vista agregada. Te quedas cambiando entre paneles de tmux, desplazandote por el historial de la terminal y reconstruyendo el estado del proyecto en tu cabeza.

Eso funciona para dos agentes. Se desmorona con cinco.

Como los agentes reportan trabajo a traves de beads

La base es beads, un issue tracker de codigo abierto, nativo de Git, construido exactamente para este flujo de trabajo. beads les da a los agentes una forma estructurada de registrar lo que estan haciendo, y te da a ti una forma estructurada de consultarlo. Cada accion del agente se convierte en un comando CLI que escribe en una base de datos local.

Cuando un agente toma trabajo:

bd update bb-f8o --status in_progress --assignee agent-3

Cuando descubre un prerrequisito y crea un nuevo issue:

BLOCKER=$(bd create \
  --title "Auth middleware needs rate limiting before deploy" \
  --type task --priority 1 --json | jq -r '.id')

bd dep add bb-f8o "$BLOCKER"

Cuando termina:

bd update bb-f8o --status closed
bd comments add bb-f8o --author agent-3 \
  "DONE: Implemented request throttling. Commit: a1c9e4f"

Cada uno de esos comandos toma milisegundos. Cada uno escribe en la misma base de datos local. Los agentes no necesitan tokens de API, clientes HTTP ni flujos de autenticacion. Ejecutan comandos de shell, de la misma manera que ejecutan git commit o npm test.

Despues de unas horas de trabajo en paralelo, esa base de datos contiene la imagen completa: quien esta trabajando en que, que esta bloqueado, que acaba de terminar y que esta disponible. La informacion existe. El problema es verla.

Lo que bd list no puede mostrarte

Puedes consultar la base de datos desde la terminal:

bd list --status=in_progress
bd blocked
bd ready

Cada uno de esos comandos devuelve datos utiles. Pero los devuelve como texto plano, una captura a la vez. Para entender el estado de tu proyecto, ejecutas bd list, luego bd show en algunos issues, despues bd dep list para ver que esta bloqueando que, y luego bd blocked para encontrar agentes estancados. Armas el rompecabezas manualmente.

Cuando los agentes se mueven rapido (cerrando tres issues en 90 segundos, cada uno desbloqueando trabajo diferente aguas abajo), el CLI no puede seguir el ritmo del cambio. Para cuando terminas de leer bd blocked, dos de esos bloqueadores ya se resolvieron.

Lo que Beadbox te muestra

Beadbox es una aplicacion de escritorio nativa que observa tu directorio .beads/ y renderiza el estado completo del proyecto en tiempo real. Cuando un agente ejecuta bd update en una terminal, Beadbox captura el cambio en el sistema de archivos y lo envia a la interfaz via WebSocket en milisegundos. Sin polling. Sin boton de actualizar. Sin cambiar entre paneles de tmux para descubrir quien hizo que.

Esto es lo que te da concretamente:

Arboles de progreso de epics. Tu funcionalidad de nivel superior muestra 7 de 12 subtareas completas. Expandela y veras que subtareas estan en progreso (y que agente es dueno de cada una), cuales estan bloqueadas y cuales acaban de quedar disponibles. Un vistazo reemplaza una docena de comandos bd show.

Badges de dependencia en cada issue. Ves al instante que bb-q3l esta esperando a bb-f8o sin ejecutar un solo comando. Cuando bb-f8o se cierra, bb-q3l se ilumina como desbloqueado. La cascada es visible mientras sucede.

Resaltado de tareas bloqueadas. Cada issue bloqueado aparece con sus dependencias de bloqueo listadas en linea. No buscas bloqueadores. Estan en pantalla, ordenados por prioridad, en el momento en que existen.

Cambio multi-workspace. Si ejecutas agentes en multiples proyectos, cambia entre bases de datos de beads desde un menu desplegable. Cada workspace recuerda sus propios filtros y estado de vista.

Sincronizacion en tiempo real. El pipeline de actualizacion es fs.watch en el directorio .beads/, enviado por WebSocket a la interfaz de React. La propagacion en menos de un segundo significa que ves la actividad del agente mientras sucede, no en un intervalo de polling de 30 segundos.

El flujo de trabajo de monitoreo

Una vez que Beadbox esta abierto junto a tu sesion de tmux, el monitoreo se convierte en reconocimiento de patrones en lugar de investigacion activa. Esto es lo que debes observar:

Tareas en progreso estancadas. Un agente que reclamo una tarea hace dos horas y no la ha actualizado esta atascado o se cayo. En un flujo humano, dos horas no significan nada. Para un agente, ese silencio es una bandera roja. Revisa el panel de tmux, empuja al agente o reasigna el trabajo.

Acumulacion de tareas bloqueadas. Si las tareas bloqueadas se acumulan y todas apuntan a la misma dependencia sin resolver, esa dependencia es tu ruta critica. Reprioriza, asigna a tu agente mas rapido o resuelvela tu mismo.

Dependencias falsas. Los agentes declaran dependencias de mas durante la planificacion. Modelan lo que creen que necesitaran basandose en su lectura inicial del codigo. Una vez que el trabajo comienza, muchas de esas dependencias resultan innecesarias. Cuando detectas una tarea bloqueada cuya dependencia parece incorrecta, eliminala:

bd dep remove bb-q3l bb-f8o

Ese unico comando desbloquea la tarea al instante. En Beadbox, la ves pasar de bloqueada a disponible en tiempo real.

Trabajo listo sin asignar. Despues de una cascada de desbloqueos, podrias tener cinco tareas repentinamente disponibles sin agente asignado. Ese es tu momento de despacho. Apunta a los agentes inactivos al trabajo listo de mayor prioridad.

El ciclo de triage es simple: busca bloqueos, resuelve o reasigna, busca trabajo listo, despacha. Beadbox convierte cada busqueda en un vistazo en lugar de una secuencia de comandos CLI.

Por que esto importa a escala

Dos agentes, puedes supervisarlos mirando terminales. Tres o cuatro, empiezas a perder el hilo. Con seis o diez, necesitas instrumentacion.

Los agentes en si no son el cuello de botella. Claude Code es rapido. Escribe codigo, ejecuta tests e itera sobre fallos sin esperarte. El cuello de botella es la capacidad del supervisor para ver todo el tablero: que agentes son productivos, cuales estan atascados, por donde corre la ruta critica y que acaba de abrirse.

Un dashboard visual en tiempo real convierte eso de una investigacion (ejecutar cinco comandos, leer el output, mantener el estado en tu cabeza) en un escaneo (mirar la pantalla). Esa diferencia se acumula a lo largo de un dia completo de coordinacion de agentes en paralelo.

Primeros pasos

Instala Beadbox con Homebrew:

brew tap beadbox/cask && brew install --cask beadbox

Si tus agentes ya usan beads, Beadbox detecta los workspaces .beads/ existentes automaticamente. Abre la app y tus issues estan ahi. Sin paso de importacion, sin creacion de cuenta, sin sincronizacion en la nube. Tus datos permanecen en tu maquina.

Si eres nuevo en beads, instala el CLI (go install github.com/steveyegge/beads/cmd/bd@latest), ejecuta bd init en tu proyecto y empieza a despachar trabajo a tus agentes. Beadbox muestra todo lo que hacen en el momento en que lo hacen.

Beadbox funciona en macOS, Linux y Windows. Es gratis mientras esta en beta.