Escritura tecnica del proyecto initech.
28 de marzo de 2026
Por que construimos un multiplexor de terminal para agentes de IA
Construimos un TUI en Go que gestiona multiples agentes de Claude Code ejecutandose en paralelo. Reemplazo a tmux como nuestro runtime de sesion.
Dale a cada agente una terminal ejecutando Claude Code con instrucciones especificas del rol. Un agente supervisor coordina. Los agentes ingenieros implementan. Un agente QA valida. Un agente shipper publica releases. Cada agente recibe un CLAUDE.md que codifica su identidad, restricciones, flujo de trabajo y protocolo de comunicacion.
Ejecutamos esto en cuatro proyectos antes de construir initech. Produjo software real: ingenieria en paralelo, QA independiente, gates de release, memoria institucional entre sesiones.
tmux falla de tres maneras que empeoran a medida que agregas agentes.
tmux send-keys no tiene garantia de entrega. Envias un mensaje al panel de un agente y esperas que llegue. Cuando no llega, no hay error. Un reporte de finalizacion de eng a super se pierde, super no sabe que eng termino, QA nunca se despacha y el bead se estanca por una hora.
Un agente colgado y uno productivo se ven identicos en tmux. Terminado y en medio del trabajo se ven identicos. La unica forma de saberlo es revisar cada panel. Con 9 agentes, son 9 revisiones manuales cada 10-15 minutos.
tmux no sabe que trabajo existe, quien esta asignado a que, o que un agente acaba de marcar una tarea como lista para QA. Toda la orquestacion vive en la ventana de contexto del supervisor. El contexto se compacta. Los mensajes se pierden. El agente supervisor olvida que eng termino. La cadena de despacho se estanca.
tmux es un multiplexor de terminal de proposito general haciendo un trabajo que necesita inteligencia a nivel de aplicacion.
Cada sesion ejecuta un socket de dominio Unix. initech send escribe texto al PTY de un agente a traves del emulador, luego confirma la entrega. El emisor recibe un OK explicito o un error en segundos.
$ initech send eng1 "fix the auth bug in middleware.go" $ initech peek eng1 -n 20
Primero intentamos hacer tail del log de sesion JSONL. No confiable: Claude escribe al JSONL en los limites de conversacion, no de forma predecible. Durante una pausa de pensamiento de 45 segundos, cero entradas. Cualquier timeout es incorrecto para algun valor del timeout.
Lo que funciona: rastrear cuando el PTY produjo salida por ultima vez. El spinner de Claude Code se anima a 10-30 fps durante el pensamiento. El unico estado con cero salida es inactivo-en-prompt. Un umbral de recencia de 2 segundos da una deteccion binaria limpia.
Punto verde significa trabajando. Gris significa inactivo. Amarillo significa inactivo con tareas esperando. La superposicion muestra el estado de cada agente sin abrir ningun panel.
JSONL fallo para deteccion de actividad pero funciona para eventos semanticos. Los logs de sesion contienen resultados de uso de herramientas, mensajes del asistente y secuencias de error. El sistema de eventos los analiza para:
* Finalizacion de bead: el agente ejecuto bd update --status ready_for_qa
* Estancamiento: sin salida por 10+ minutos con un bead asignado
* Bucles de error: 3+ fallos consecutivos de herramientas
* Reclamos de beads: auto-detectados desde comandos bd, sin llamada CLI extra necesaria
Los eventos se muestran como notificaciones toast. "eng1 completed ini-bhk.3" aparece en verde antes de que super lo reporte.
La cinta de cada agente muestra su bead actual. La superposicion muestra el estado de cada agente de un vistazo. Cuando un agente queda inactivo despues de tener un bead, el TUI le dice al agente supervisor directamente: "[from initech] eng1 is now idle (bead: ini-bhk.3). Check if work is complete."
Cada numero de arriba fue producido por la herramienta misma. initech gestiono los agentes que construyeron initech.
El TUI es el runtime. Las plantillas son la inteligencia. Un CLAUDE.md malo produce mala salida sin importar que tan bueno sea el TUI. Reescribimos las 11 plantillas tres veces, cada vez codificando lecciones de fallos reales: agentes ingenieros saltandose comentarios de PLAN, agentes QA aprobando sin revisar, el agente supervisor haciendo trabajo en vez de despachar.
Tres enfoques antes de que la recencia de bytes del PTY funcionara. Tail de JSONL: demasiado lento. Tasa de salida de terminal: falsos positivos de SIGWINCH. Deteccion de prompt: fragil a cambios de UI. El enfoque del spinner solo funciona porque Claude Code siempre produce salida cuando trabaja. Una pantalla estatica de "thinking..." lo romperia.
El fallo numero uno del agente supervisor: hacer implementacion en vez de despachar. Despachar se siente lento. Pero el punto central de multi-agente es la especializacion. "No usar agentes" es ahora el primer modo critico de falla en la plantilla del supervisor.
Cada agente eventualmente olvida comentar PLAN antes de codificar, o hacer push antes de marcar ready_for_qa, o limpiar su display de bead. Auto-notify existe porque los agentes olvidan reportar finalizacion. Los guardrails ayudan pero no eliminan esto. El cumplimiento del proceso es un gradiente, no un binario.
Portabilidad de sesion no se ha iniciado. Mover una sesion entre maquinas (MacBook a workbench) requiere rsync manual. El PRD describe un comando initech migrate que aun no existe.
Gestion de recursos esta detras de un flag. Auto-suspender/reanudar bajo presion de memoria (la funcionalidad que duplicaria la capacidad efectiva de agentes en un laptop de 36GB) esta implementada pero restringida detras de --auto-suspend porque la politica no se ha probado lo suficiente en sesiones reales.
Onboarding es tosco. Un nuevo usuario que ejecuta initech por primera vez ve 7 paneles sin guia. Los tips de la barra de estado rotan en la parte inferior, pero no hay una guia del operador que documente el flujo de trabajo completo. La herramienta fue construida por su propio usuario, y se nota.
Adopcion temprana. initech se ha usado en multiples proyectos, pero la base de usuarios aun es pequena. Mas uso en el mundo real revelara brechas que el dogfooding no encontro.
curl -fsSL https://initech.sh/install.sh | bash mkdir myproject && cd myproject initech init initech
Codigo fuente: github.com/nmelo/initech