Multiplexores

Collie controla un multiplexor por instalación: Herdr, tmux o zellij. Herdr es la opción predeterminada. Esta página describe cómo apuntar Collie a cualquiera de los tres, qué puede responder cada backend y las balizas que Collie utiliza para detectar un agente en un panel.

Configurar Collie para un multiplexor

Indique el backend en COLLIE_MUX, apúntelo a un endpoint, reinicie e instale los hooks de beacon.

Experimental en 1.0. tmux y zellij se probaron en tmux 3.6b y zellij 0.44.2, en un solo host. Herdr es el backend predeterminado y el principal admitido. Se buscan evaluadores: abra un problema en AltanS/collie con el título tmux: … o zellij: …, indicando el multiplexor, la versión, el SO y el comportamiento observado.

Indique el multiplexor en la línea de comandos:

COLLIE_MUX=herdr collie start
COLLIE_MUX=tmux collie start
COLLIE_MUX=zellij collie start

Defina el endpoint cuando el destino predeterminado no sea el deseado:

# in your .env: ~/.config/collie/.env, or Herdr's plugin config dir on a Herdr
# install. See Configure for the full precedence.
COLLIE_MUX=tmux
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock
COLLIE_MUX_ENDPOINT_ZELLIJ=collie-zellij

# only if the binary sits somewhere unusual
# COLLIE_TMUX_BIN=/usr/bin/tmux
# COLLIE_ZELLIJ_BIN=/home/you/.local/bin/zellij

Herdr no tiene una variable de endpoint aquí: su socket es HERDR_SOCKET_PATH, no un nombre COLLIE_MUX_ENDPOINT_.

Ese socket es el local y ningún otro. Herdr 0.9.0 puede guardar máquinas SSH y mostrar varios servidores en un solo cliente Herdr, y Collie no lee ninguno de ellos, por lo que una máquina guardada en Herdr no es un miembro del pack; solo un pack de Collie lleva las sesiones de otra máquina al teléfono.

Luego reinicie, instale los hooks de baliza e inicie un agente donde el teléfono pueda detectarlo:

collie restart                 # after every .env edit
collie hooks install claude    # once per host, tmux and zellij only

# open a window or a tab for the agent
tmux -S /run/user/1000/collie-tmux.sock new-window -n claude
zellij --session collie-zellij action new-tab --name claude

claude                         # in that window or tab

Qué hicieron esos comandos

COLLIE_MUX en la línea de comandos define la opción para esa ejecución y para todas las posteriores. start escribe el nombre en .env, por lo que ejecutar collie start más tarde controlará el mismo multiplexor.

Con COLLIE_MUX sin definir, start busca Herdr, tmux y zellij, solicita seleccionar un backend y escribe la respuesta en .env. Para consultar la referencia de configuración completa, véase MUX_CONTRACT.md → Apuntar Collie a un multiplexor.

collie hooks install claude instala los hooks beacon de Collie, requeridos por tmux y zellij. Estos exponen los paneles como shells genéricas, por lo que sin hooks cada panel aparece como bash.

El comando actualiza ~/.claude/settings.json y mantiene intactas las configuraciones de los proyectos (detalles a continuación). Las instancias de Claude en ejecución no recargan su configuración; deben reiniciarse.

Nota. Herdr no es necesario en este modo. Con COLLIE_MUX=tmux o COLLIE_MUX=zellij, el bridge solo carga el adaptador seleccionado e ignora el socket de Herdr. El descubrimiento multisesión entre las raíces de configuración de Herdr queda desactivado (bridge/index.ts). No es necesario tener Herdr instalado ni en ejecución, y .env reside en ~/.config/collie/ en lugar de en el directorio de configuración de plugins.

Notas sobre tmux

COLLIE_TMUX_BIN suele dejarse sin definir. Collie comprueba una lista de rutas estándar y no lee PATH, variable que los servicios en segundo plano y las acciones de Herdr no comparten con las shells de inicio de sesión.

Nota. Mantenga cortas las rutas de sockets. Los sockets de dominio Unix con más de unos 100 caracteres fallan al conectar y tmux devuelve error connecting to … (File name too long). Utilice /run/user/<uid>/ o /tmp en lugar de una ruta de directorios profunda.

En versiones de tmux anteriores a 3.7 con window-size establecido en manual, crear una ventana bloquea el servidor. Collie bloquea la creación de ventanas en este estado e indica ejecutar tmux set -g window-size latest; Requisitos enumera las versiones probadas.

Notas sobre zellij

Si su distribución carece de paquetes de zellij, descargue un binario desde versiones de GitHub de zellij y colóquelo en su PATH.

Si se deja el endpoint vacío, se toma por defecto la única sesión en ejecución. Si existen cero o varias sesiones, Collie se detiene con un error en lugar de seleccionar una. Si una sesión nombrada finaliza, Collie la reporta por su nombre en vez de cambiar a una activa.

Zellij requiere XDG_RUNTIME_DIR para localizar sesiones. Si Collie reporta todas las sesiones como finalizadas, verifique que el servicio de systemd incluya esta variable de entorno (contrato).

Las sesiones de zellij persisten independientemente de su terminal inicial. Cree una sesión con zellij -s collie-zellij y desacople mediante Ctrl o d. En hosts sin pantalla, zellij attach --create-background collie-zellij inicia una sesión desacoplada directamente (verificado en zellij 0.44.2).

Nota. Collie gestiona las sesiones activas, pero no las crea ni las reinicia.

¿Funcionó?

collie doctor   # the `mux` check names the multiplexer, its endpoint,
                # and whether it answered

# `[bridge] mux: tmux · socket /run/user/1000/collie-tmux.sock`, printed at
# startup; a multiplexer it cannot reach is one warning line more
collie logs

# the herd, as the phone is given it
curl -s http://127.0.0.1:8787/api/snapshot | head -c 400

Esta llamada curl funciona sin encabezados de autenticación. Las solicitudes de lectura omiten la validación de dispositivos incluso cuando COLLIE_DEVICE_HEADER está habilitado (Configuración). Solo las acciones de escritura requieren el encabezado configurado.

Revise la interfaz móvil: el panel debe mostrar su ventanas de tmux o pestañas de zellij, y el panel de Claude debe identificarse como un agente en lugar de bash. Si los paneles aún se muestran como shells estándar, verifique la instalación del hook de beacon a continuación.

Collie escribe hooks en la propia configuración de Claude

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Dado que tmux y zellij exponen los paneles como shells genéricas, los agentes deben anunciarse. Esto requiere instalar los hooks beacon de Collie en la configuración de Claude Code.

La salida hace referencia a la ruta bin/collie de este repositorio. Las instalaciones por paquete utilizan la ruta del binario instalado (~/.local/bin/collie o ~/.local/share/collie/current/bin/collie) en lugar de directorios con versiones, lo que garantiza que los enlaces sigan siendo válidos tras las actualizaciones.

Detalles de comportamiento para cambios de configuración de Claude:

• —
  Modifica el global ~/.claude/settings.json y cualquier CLAUDE_CONFIG_DIR activo. Los archivos .claude/settings.json a nivel de proyecto no se modifican.
• —
  Inyecta hooks de cinco etiquetados como # collie-beacon v1 con tiempos de espera de 10 segundos. Se conservan los hooks existentes. hooks uninstall claude elimina únicamente las entradas de Collie.
• —
  Los procesos de Claude en ejecución no recargan la configuración. Reinicie los agentes para aplicar los cambios.
• —
  Solo Linux. La comprobación de actividad del agente depende de /proc. Otros sistemas operativos no emiten beacons.
• —
  Los beacons son específicos de cada multiplexor. Registran identificadores de panel y de sesión para el backend activo. Cambiar COLLIE_MUX invalida los beacons existentes. Los beacons antiguos permanecen en el disco hasta que se eliminan, visibles en el recuento de beacons de collie doctor.
• —
  Si se utiliza COLLIE_STATE_DIR, expórtelo en el entorno de shell del agente. collie beacon emit lee esta variable directamente; de lo contrario, los beacons se escriben en el directorio de estado predeterminado donde el bridge no los encontrará.

collie doctor incluye una comprobación de diagnóstico de beacon-hooks-claude que señala hooks faltantes o rutas rotas a repositorios movidos. Para obtener detalles sobre el tiempo de ejecución, consulte Beacons de agentes.

Qué cambia en comparación con Herdr

La siguiente tabla resume las diferencias principales. Consulte MUX_CONTRACT.md para ver la especificación exacta.

Sin beacons activos, tmux y zellij presentan los paneles como shells directos, y el historial del panel se marca como no disponible en lugar de devolver contenido vacío.

Dos diferencias en el teléfono

• —
  "sincronizado hace Ns": Este indicador aparece en la cabecera del panel para mostrar la antigüedad de los datos. Se muestra solo cuando el backend depende de un sondeo programado, como zellij (intervalo de sondeo de hasta 12 s). Herdr y tmux envían los cambios de estado de inmediato, por lo que se omite la etiqueta de actualización.
• —
  "Mostrar en terminal": Esta acción de panel enfoca el panel seleccionado en la terminal activa del host. Está desactivado en zellij porque el comando de enfoque de zellij acepta la instrucción sin cambiar el estado de la vista.

Nota. La interfaz móvil nunca cambia el foco del terminal del host de forma automática. Solo la acción explícita "Show in terminal" actualiza la pantalla. Navegar por el panel o abrir paneles no afecta al cursor activo del host (ADR 0031).

Consejos para tmux: recuperar las ventanas tras reiniciar

Collie no almacena el estado del multiplexor. Reiniciar un servidor tmux destruye sus ventanas y deja el panel vacío.

Es posible gestionar la restauración de estado mediante plugins estándar de tmux: tpm para la gestión de plugins, tmux-resurrect para guardar árboles de sesiones y tmux-continuum para instantáneas automatizadas.

Estas herramientas restauran las disposiciones de las ventanas y los directorios de trabajo. Para restaurar el contexto de la conversación, utilice los flags integrados de Claude: claude --resume o claude --continue.

Nota. Los procesos de agentes en ejecución no se conservan. Reinicie Claude Code manualmente tras la recuperación.

Consejos para zellij: tras reiniciar no hay nada que restaurar

Zellij no proporciona un equivalente a tmux-resurrect. Las sesiones que persisten tras desconectar el terminal se muestran como (EXITED - attach to resurrect), y conectarse a ellas vuelve a ejecutar los comandos de la sesión.

Nota. Debido a que conectarse genera efectos secundarios, Collie no se conecta a las sesiones ni las resucita. Las sesiones finalizadas aparecen como inaccesible, y la interfaz de usuario muestra un aviso de desconexión en lugar de una lista de sesiones vacía.

Tras reiniciar el sistema, inicie la sesión manualmente (zellij -s collie-zellij o zellij attach --create-background collie-zellij en sistemas sin interfaz gráfica) y ejecute los agentes en su interior. Reconéctese a sesiones de agentes anteriores mediante claude --resume o claude --continue.

Beacons de agentes (opcional, Linux)

Un beacon es el modo en que un agente se identifica ante Collie en tmux y zellij, donde un panel se mostraría de otro modo como una shell genérica.

$ collie hooks install claude
$ collie hooks status
would install: /home/you/collie/bin/collie beacon emit  (this checkout)
/home/you/.claude/settings.json: installed (v1)

Un hook en la configuración de Claude Code ejecuta collie beacon emit, lo que escribe un archivo que contiene el nombre del harness, la sesión y el panel de destino. Herdr realiza este seguimiento de forma nativa. Los detalles de configuración se encuentran en Configurar Collie para un multiplexor; esta sección describe el mecanismo.

La ruta anterior hace referencia a bin/collie desde la copia local. Una instalación binaria apunta a ~/.local/bin/collie, o a ~/.local/share/collie/current/bin/collie cuando ese nombre no está enlazado, como se describió anteriormente. El comando status no realiza escrituras.

Ejecutar hooks uninstall claude elimina únicamente las entradas agregadas por Collie. Modifica la configuración de Claude de global, no los archivos a nivel de proyecto. Esto solo aplica a Linux: la comprobación de actividad inspecciona /proc, y Collie no escribe beacons en otros sistemas operativos.

Claude pasa a ser visible inmediatamente tras el inicio. Dado que el hook se activa en SessionStart, un panel abierto en espera de entrada se muestra como un agente inactivo en lugar de una shell.

La visibilidad finaliza cuando el proceso termina. Collie verifica el PID emisor en cada comprobación, por lo que una vez que el agente finaliza, el panel pasa a reportarse de inmediato como una shell estándar en lugar de permanecer en un estado desconocido.

Collie no elimina el archivo beacon para hacer esto: el archivo permanece en el disco, collie doctor lo reporta en beacons como expirado, y la siguiente invocación del hook lo sobrescribe.

Esto permite que el panel de control identifique los paneles por el nombre del agente en lugar de bash. Permite que "needs you" ordene los paneles según el estado de bloqueo y proporciona el estado necesario para las alertas. El historial del panel también depende del beacon para proporcionar la clave de sesión utilizada por el journal.

Nota. Los beacons no proporcionan un canal de control. Un beacon solo determina lo que Collie muestra y consulta. No puede enviar texto, inyectar pulsaciones de teclas, renombrar paneles, cerrar sesiones ni eludir controles de acceso. El modelo de amenazas y los campos omitidos se documentan en ADR 0024.