fleetmux

Un equipo, no un único asistente

Gestiona equipos de IA como gestionas contenedores.

fleetmux ejecuta un agente supervisor y N agentes workers como sesiones de terminal visibles. El supervisor solo evalúa y reparte el trabajo; los workers solo ejecutan; quien decide cuándo está terminado el trabajo es un daemon, no los modelos. Una sesión que se acerca a su límite de contexto cede el relevo a una sesión nueva mediante una nota de traspaso escrita, de modo que una misma tarea puede durar horas a lo largo de muchas sesiones de modelo.

Empezar GitHub

Un terminal animado: el supervisor divide el objetivo y reparte el trabajo, dos workers ejecutan, el daemon comprueba cada entregable declarado, worker-1 escribe una nota de traspaso y pasa a ser worker-1.1 en el mismo panel, y la tarea queda COMPLETED.

La disposición real: el supervisor arriba a la izquierda, history y daemon abajo a la izquierda, los workers como pestañas a la derecha.

Jefe de proyecto

Un jefe de proyecto, no un secretario

Los agentes tipo asistente personal ya pueden lanzar subagentes, ejecutar tareas programadas y pasar de un modelo a otro ante un fallo. fleetmux añade lo que hace un jefe de proyecto:

Tapa cerrada, sigue

Cierra la tapa. Cámbiate de sitio. Abre. Sigue.

Cierra el MacBook, llévalo a otro sitio, ábrelo, vuelve a conectarte y la ejecución continúa. El daemon distingue una máquina que durmió de un enlace que se cayó: cuando el hueco entre dos ticks supera dos periodos de renovación de los puentes, da a cada sesión tres periodos para volver a dar señal de vida antes de darla por perdida. Un arranque que choca con un error de red no se bloquea: espera 30, 60, 120 segundos y luego reintenta cada 300. Y sin conexión no se reinicia nada: antes de reiniciar cualquier sesión el daemon comprueba la red, y si no hay red solo espera, sin gastar intentos ni arrancar una generación nueva. La ejecución no se pausa, nadie tiene que reanudarla a mano y sigue en cuanto la red responde.

01

Entregas aceptadas por el programa

Si los entregables existen, si contienen lo que deben y si las pruebas pasan lo decide el daemon, no se toma del informe del propio modelo.

02

Sesiones que continúan sin fin

Cerca del límite de contexto, una sesión escribe una nota de traspaso y una sesión nueva ocupa su lugar; una sesión congelada se reinicia en el sitio; el daemon y el supervisor se vigilan mutuamente.

03

Reparto según una matriz de capacidades

Antes de cada envío, el asesor elige el modelo y el nivel de esfuerzo a partir de una matriz de capacidades (dominio × tipo de tarea × modelo, cada celda respaldada por evidencia), y la elección debe superar una comprobación contra esa matriz; un límite de uso hace pasar la ranura al siguiente modelo utilizable de la cadena de su rol, o pone la tarea en pausa.

04

Visible de principio a fin

Cada agente es una sesión de terminal visible que puedes observar y en la que puedes intervenir cuando quieras.

05

CLI oficiales, tu propio inicio de sesión

Cada agente se ejecuta en la CLI de su proveedor con tu propio inicio de sesión; no se extrae ningún token, no se suplanta ningún cliente y ninguna llamada a la API pasa por un proxy.

06

Un presupuesto por tarea

Una tarjeta de presupuesto limita llamadas, rondas, horas y cuota por cuenta; una tabla de límites de uso baja un nivel de modelo o pausa la ejecución para reanudarla más tarde.

07

Equipos de equipos

Un worker puede convertirse en el líder de su propia subflota, así que una sola flota residente puede llevar varias líneas de negocio, cada una arrancada y detenida según su propio horario.

Cómo funciona

El recorrido de una tarea

La tarea lleva su propia definición de terminado: los entregables que debe producir, la extensión de cada uno y lo que cada uno debe contener.

Tarea objetivo + entregables declarados Supervisor divide y reparte Workers un paso cada uno Daemon aceptación literal COMPLETED cada entregable verificado rechazo — tres rechazos bloquean la tarea
El supervisor solo puede declarar archivos que comprobar, nunca comandos que ejecutar.
worker-1 contexto 60 % worker-1.1 nota de traspaso worker-1.2 misma pestaña
El sucesor ocupa la pestaña de su predecesor; la pantalla retirada y la nota pasan a la página history.

Rotación de contexto, no compactación

Al 60 % de la ventana de contexto, la sesión escribe una nota de traspaso de tres secciones, la pantalla antigua pasa a la página history y un sucesor arranca en el mismo sitio y lee la nota. Si el modelo no escribe, se usa un esqueleto automático; que falte la nota no bloquea por sí solo la rotación.

Una sesión congelada se reinicia en el sitio; el daemon y el supervisor se vigilan mutuamente.

CLI mixtas

Mezcla las CLI que ya usas

Claude Code oficial, Codex CLI oficial, Pi (modelos de Codex y modelos locales) y opencode conviven en una misma flota. La matriz de abajo enumera cada par supervisor × worker que conoce la tabla de pares, en modo tarea y en modo servicio.

Pares supervisor × worker, modo tarea. Un par que no figure en la tabla de pares no está admitido.
Supervisor ↓ / worker → Claude Code Codex CLI Pi opencode dsh
Pi superado no admitido superado solo prueba de humo superado
Codex CLI superado solo prueba de humo superado superado no admitido
Claude Code superado no admitido superado no admitido no admitido
Pares supervisor × worker, modo servicio. Un par que no figure en la tabla de pares no está admitido.
Supervisor ↓ / worker → Claude Code Codex CLI Pi opencode dsh
Pi superado no admitido superado superado no admitido
Codex CLI superado no admitido superado solo prueba de humo no admitido
Claude Code superado no admitido superado no admitido no admitido
superó una prueba de humo real (1 supervisor + 2 workers, 4 comprobaciones) solo modo smoke (arranca con --lifecycle smoke) no admitido (no está en la tabla de pares)

Los workers de Codex (codex+codex) aún no están verificados; opencode nunca es supervisor, y dsh es un backend solo para workers en modo tarea. Los pares y su estado (verificado / no verificado = solo --lifecycle smoke / rechazado) están en fleetmux/config/fleet.yaml#cli_pairs; cualquier par que no figure en la tabla se rechaza con un motivo antes de provisionar.

par de noche: supervisor Pi + workers Pi 
fleetmux start --supervisor-cli pi --worker-cli pi \
  --supervisor-pi-model openai-codex/gpt-6-astra --supervisor-pi-thinking high \
  --pi-model flashnext/<local-model> --workers 2 --lifecycle <mode> \
  --allow-unsandboxed-pi --allow-development-v2

Casos de uso

Para qué está pensado

Cada start indica un --lifecycle, que decide qué significa «terminado» y cómo se cierra la ejecución.

01

Operaciones que solo pueden usar modelos locales

Algunos entornos solo permiten modelos que se ejecutan en tus propias máquinas, y a los modelos locales se les da mal trabajar juntos. fleetmux quita la colaboración a los modelos y se la da al daemon: el supervisor solo elige el siguiente paso, un worker solo lo lleva a cabo, y el daemon decide cuándo ha terminado un turno, si el resultado existe y cuándo una sesión cede el relevo. --max-busy mantiene las peticiones simultáneas por debajo del límite de memoria del servidor de inferencia; el Redis privado de la flota solo escucha en un socket Unix y no abre ningún puerto.

02

Vigilancia de trading: estrategias confiadas a la IA, revisadas al dispararse

Tu propio programa vigila precios e indicadores; cuando se cruza un nivel o un parámetro envía una petición, y el worker que tiene ese rol hace una revisión completa y responde en JSON. Una petición que indica to se salta el turno del supervisor, y el daemon comprueba los campos de la respuesta antes de que tu programa la lea. La flota no lanza órdenes ni conoce ningún calendario.

03

Informe de investigación programado

El programador de tareas de quien llama arranca una flota a horas fijas del día hábil: un supervisor y dos workers de Claude Code con skills de investigación y un MCP de búsqueda web. El objetivo declara el archivo del informe y las secciones que debe contener; el daemon lo acepta de forma literal, impone a la ejecución un presupuesto de tiempo estricto y cierra el espacio de trabajo al terminar.

04

Servicio de evaluación residente

Otro programa envía peticiones JSON; una petición que indica to va directamente al worker de ese rol. El daemon comprueba cada respuesta frente a reply.required y reply.allowed, y quien llama detiene la flota fuera de su horario de trabajo con pause y resume.

Inicio rápido

En marcha en tres pasos

Abre un terminal de cmux, configura tu proveedor y modelo de Pi, y sustituye local/my-model más abajo.

  1. Comprueba los requisitos

    • macOS con cmux ≥ 0.64.25 (new-surface --command); ejecuta start dentro de un terminal de cmux.
    • Para los agentes de Codex: Codex CLI ≥ 0.156.
    • redis-server en el PATH (brew install redis); cada ejecución arranca su propia instancia privada y nunca toca localhost:6379.
    • Python 3.14 y los paquetes de requirements.txt.

  2. Instalación

    install 
    git clone https://github.com/justindbca/fleetmux && cd fleetmux
pip install -e .

  3. Arranca tu primera flota

    primera flota 
    fleetmux start --workers 2 --supervisor-cli pi --worker-cli pi --lifecycle <mode> \
  --pi-model local/my-model --allow-unsandboxed-pi --allow-development-v2
echo '{"goal": "Survey the three most-cited papers on X and write a comparison",
       "hours": 4,
       "artifacts": [{"path": "worker-1/report.md", "min_chars": 800, "contains": ["Conclusion"]}]}' \
  | fleetmux task -                           # hand the goal to the supervisor
fleetmux status                               # task + per-agent state, context usage, inbox depth
fleetmux stop                                 # cancel; confirm runtime retirement before Redis shutdown

    Los arranques nuevos requieren Redis v2 y una autorización explícita del modo de desarrollo; es una integración de desarrollo, no una aceptación de producción.

    Limitaciones conocidas

Leer el inicio rápido completo →