Multiplexeurs

Collie pilote un multiplexeur par installation : Herdr, tmux ou zellij. Herdr est l'option par défaut. Cette page explique comment orienter Collie vers l'un des trois, à quoi chaque backend peut répondre, et les balises que Collie utilise pour détecter un agent dans un panneau.

Pointer Collie vers un multiplexeur

Indiquez le backend dans COLLIE_MUX, pointez-le vers un endpoint, redémarrez et installez les hooks de balise.

Expérimental dans la version 1.0. tmux et zellij ont été testés sur tmux 3.6b et zellij 0.44.2, sur un seul hôte. Herdr est le backend par défaut et le backend principal pris en charge. Testeurs recherchés : ouvrez une issue sur AltanS/collie intitulée tmux: … ou zellij: …, en précisant votre multiplexeur, sa version, l'OS et ce que vous avez observé.

Indiquez le multiplexeur en ligne de commande :

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

Définissez l'endpoint lorsque la cible par défaut n'est pas celle souhaitée :

# 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 n'a pas de variable d'endpoint ici : son socket est HERDR_SOCKET_PATH, pas un nom de COLLIE_MUX_ENDPOINT_.

Ce socket est le socket local et aucun autre. Une machine enregistrée dans Herdr n'est pas membre du crew, et seul un crew Collie transmet les sessions d'une autre machine au téléphone. Ce que représente chaque liste, et pourquoi elles diffèrent, est expliqué dans Machines Herdr et le crew.

Ensuite, redémarrez, installez les hooks de balise et démarrez un agent là où le téléphone peut le voir :

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

Ce que ces commandes ont fait

COLLIE_MUX sur la ligne de commande définit le choix pour cette exécution et pour chaque exécution ultérieure. start écrit le nom dans .env, de sorte que l'exécution ultérieure de collie start pilote le même multiplexeur.

Si COLLIE_MUX n'est pas défini, start recherche Herdr, tmux et zellij, demande de choisir un backend et écrit la réponse dans .env. Pour la référence complète de configuration, consultez MUX_CONTRACT.md → Pointer un collie vers un multiplexeur.

collie hooks install claude installe les hooks beacon de Collie, requis par tmux et zellij. Ils exposent les volets comme des shells génériques ; sans ces hooks, chaque volet apparaît donc sous le nom bash.

La commande met à jour ~/.claude/settings.json et ne modifie pas les configurations de projet (détails ci-dessous). Les instances actives de Claude ne rechargent pas leur configuration : redémarrez-les.

Remarque. Herdr n'est pas requis dans ce mode. Avec COLLIE_MUX=tmux ou COLLIE_MUX=zellij, le bridge charge uniquement l'adaptateur sélectionné et ignore le socket de Herdr. La découverte multi-sessions à travers les racines de configuration de Herdr est désactivée (bridge/index.ts). Il n'est pas nécessaire d'installer ou d'exécuter Herdr, et .env se trouve dans ~/.config/collie/ au lieu du répertoire de configuration des plugins.

notes sur tmux

COLLIE_TMUX_BIN est généralement laissé non défini. Collie vérifie une liste de chemins standards et ne lit pas PATH, que les services d'arrière-plan et les actions Herdr ne partagent pas avec les shells de connexion.

Remarque. Utilisez des chemins de socket courts. Les sockets de domaine Unix de plus de 100 caractères environ ne parviennent pas à se connecter, et tmux renvoie error connecting to … (File name too long). Utilisez /run/user/<uid>/ ou /tmp plutôt qu'une arborescence de répertoires profonde.

Sur les versions de tmux antérieures à 3.7 avec window-size défini sur manual, créer une fenêtre fait planter le serveur. Collie bloque la création de fenêtres dans cet état et vous invite à exécuter tmux set -g window-size latest ; Prérequis liste les versions testées.

notes sur zellij

Si votre distribution ne propose pas de paquets pour zellij, téléchargez un binaire depuis releases GitHub de zellij et placez-le dans votre PATH.

Laisser le endpoint vide cible par défaut l'unique session active. Si aucune ou plusieurs sessions existent, Collie s'arrête avec une erreur au lieu d'en sélectionner une. Si une session nommée se termine, Collie la signale par son nom au lieu de basculer vers une session active.

Zellij nécessite XDG_RUNTIME_DIR pour localiser les sessions. Si Collie indique que toutes les sessions sont terminées, vérifiez que le service systemd inclut cette variable d'environnement (contract).

Les sessions zellij persistent indépendamment de leur terminal initial. Créez une session avec zellij -s collie-zellij et détachez-vous avec Ctrl o d. Sur les hôtes sans interface graphique, zellij attach --create-background collie-zellij démarre directement une session détachée (vérifié sur zellij 0.44.2).

Remarque. Collie gère les sessions actives, mais ne les crée pas et ne les redémarre pas.

Est-ce que cela a fonctionné ?

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

Cet appel curl fonctionne sans en-têtes d'authentification. Les requêtes de lecture contournent la validation de l'appareil même quand COLLIE_DEVICE_HEADER est activé (Configurer). Seules les actions d'écriture nécessitent l'en-tête configuré.

Consultez l'interface mobile : le tableau de bord doit afficher vos fenêtres tmux ou onglets zellij, et le volet Claude doit être identifié comme un agent au lieu de bash. Si les volets s'affichent toujours comme des shells standards, vérifiez l'installation des hooks beacon ci-dessous.

Collie écrit les hooks dans les paramètres 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)

Puisque tmux et zellij exposent les volets comme des shells génériques, les agents doivent s'annoncer. Cela nécessite d'installer les hooks beacon de Collie dans la configuration de Claude Code.

La sortie référence le chemin bin/collie de ce dépôt. Les installations par paquet utilisent le chemin du binaire installé (~/.local/bin/collie ou ~/.local/share/collie/current/bin/collie) plutôt que des répertoires versionnés, garantissant ainsi la validité des liens après les mises à jour.

Détails du comportement lors des modifications de la configuration de Claude :

• —
  Modifie le ~/.claude/settings.json global et tout CLAUDE_CONFIG_DIR actif. Les fichiers .claude/settings.json au niveau du projet ne sont pas modifiés.
• —
  Injecte cinq hooks étiquetés # collie-beacon v1 avec des délais d'expiration de 10 secondes. Les hooks existants sont préservés. hooks uninstall claude supprime uniquement les entrées Collie.
• —
  Les processus Claude en cours d'exécution ne rechargent pas la configuration. Redémarrez les agents pour appliquer les modifications.
• —
  Linux uniquement. La vérification de disponibilité de l'agent dépend de /proc. Les autres systèmes d'exploitation n'émettent pas de balises.
• —
  Les balises sont propres au multiplexeur. Elles enregistrent les identifiants de panneau et de session pour le backend actif. Changer de COLLIE_MUX invalide les balises existantes. Les anciennes balises restent sur le disque jusqu'à leur suppression, visibles dans le décompte beacons de collie doctor.
• —
  Si vous utilisez COLLIE_STATE_DIR, exportez-le dans l'environnement de shell de l'agent. collie beacon emit lit cette variable directement ; sinon, les balises s'écrivent dans le répertoire d'état par défaut où le pont ne les trouvera pas.

collie doctor inclut une vérification de diagnostic beacon-hooks-claude qui signale les hooks manquants ou les chemins cassés vers les dépôts déplacés. Pour les détails d'exécution, voir Balises d'agent.

Ce qui change par rapport à Herdr

Le tableau ci-dessous résume les principales différences. Consultez MUX_CONTRACT.md pour la spécification exacte.

Sans balises actives, tmux et zellij présentent les volets sous forme de shells bruts, et l'historique du volet est marqué comme indisponible plutôt que de renvoyer un contenu vide.

Deux éléments qui changent sur téléphone

• —
  « synchronisé il y a Ns » : Cet indicateur s'affiche dans l'en-tête du tableau de bord pour indiquer l'âge des données. Il s'affiche uniquement quand le backend repose sur une scrutation planifiée, par exemple zellij (intervalle de scrutation jusqu'à 12 s). Herdr et tmux transmettent les changements d'état immédiatement, le badge d'actualisation est donc omis.
• —
  « Afficher dans le terminal » : Cette action de volet place le focus sur le volet sélectionné dans votre terminal hôte actif. Elle est désactivé sur zellij car la commande de focus de zellij accepte l'instruction sans changer l'état d'affichage.

Remarque. L'interface mobile ne modifie jamais le focus du terminal hôte de manière automatique. Seule l'action explicite « Afficher dans le terminal » met à jour l'affichage. Naviguer dans le tableau de bord ou ouvrir des volets n'affecte pas le curseur actif de l'hôte (ADR 0031).

Astuces tmux : récupérer vos fenêtres après un redémarrage

claude --resume      # reconnects the conversation, not the window

Collie ne stocke pas l'état du multiplexeur. Redémarrer un serveur tmux détruit ses fenêtres, laissant le tableau de bord vide. Des plugins tmux standards restaurent les dispositions de fenêtres et les répertoires de travail : tpm pour la gestion des plugins, tmux-resurrect pour sauvegarder les arbres de sessions et tmux-continuum pour les instantanés automatiques.

Remarque. Les processus d'agents en cours d'exécution ne sont pas conservés. Redémarrez Claude Code manuellement après la récupération.

Astuces zellij : après un redémarrage, il n'y a rien à restaurer

zellij -s collie-zellij                                  # start the session
zellij attach --create-background collie-zellij          # headless: start it detached
claude --resume                                           # reconnects the agent

Zellij ne fournit pas d'équivalent à tmux-resurrect. Les sessions conservées après détachement du terminal s'affichent sous l'état (EXITED - attach to resurrect), et s'y rattacher relance les commandes de la session. Un redémarrage implique donc de recréer la session avec l'une des commandes ci-dessus et d'y lancer des agents, en reconnectant chacun avec claude --resume ou claude --continue.

Remarque. Comme le fait de s'attacher produit des effets secondaires, Collie ne s'attache pas aux sessions et ne les ressuscite pas. Les sessions terminées apparaissent comme inaccessible, et l'UI affiche une bannière de déconnexion au lieu d'une liste de sessions vide.

Balises d'agent (facultatif, Linux)

Une beacon est la façon dont un agent s'identifie auprès de Collie, sous tmux et zellij, où un panneau apparaît autrement comme un shell générique.

$ 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 dans les paramètres de Claude Code exécute collie beacon emit, qui écrit un fichier contenant le nom du harness, la session et le panneau cible. Herdr suit cela nativement. Les détails de configuration se trouvent dans Pointer Collie vers un multiplexeur ; cette section explique le mécanisme.

Le chemin ci-dessus fait référence à bin/collie depuis le clone local. Une installation binaire pointe vers ~/.local/bin/collie, ou vers ~/.local/share/collie/current/bin/collie lorsque ce nom n'est pas lié, comme décrit ci-dessus. La commande status n'effectue aucune écriture.

Exécuter hooks uninstall claude supprime uniquement les entrées ajoutées par Collie. Cela modifie votre configuration Claude global, pas les fichiers au niveau du projet. Ceci concerne uniquement Linux : la vérification de disponibilité inspecte /proc, et Collie n'écrit aucune balise sur les autres systèmes d'exploitation.

Claude devient visible dès le démarrage. Comme le hook se déclenche sur SessionStart, un panneau ouvert en attente d'une saisie s'affiche comme un agent inactif au lieu d'un shell.

La visibilité prend fin lorsque le processus se termine. Collie vérifie le PID émetteur à chaque contrôle, donc dès que l'agent s'arrête, le panneau est immédiatement signalé comme un shell standard au lieu de rester dans un état inconnu.

Collie ne supprime pas le fichier de balise pour faire cela : le fichier reste sur le disque, collie doctor le signale sous beacons comme expiré, et la prochaine exécution du hook l'écrase.

Cela permet au tableau de bord d'étiqueter les panneaux par le nom de l'agent plutôt que par bash. Cela permet de trier les panneaux selon l'état bloqué avec "a besoin de vous", et fournit l'état requis pour les alertes. L'historique du panneau s'appuie également sur la balise pour fournir la clé de session utilisée par le journal.

Remarque. Les balises ne fournissent aucun canal de contrôle. Une balise détermine seulement ce que Collie affiche et interroge. Elle ne peut pas envoyer de texte, injecter des frappes au clavier, renommer des panneaux, fermer des sessions ou contourner les contrôles d'accès. Le modèle de menace et les champs omis sont documentés dans ADR 0024.