Configurer

Par défaut, Collie ne répond qu'à un appareil appairé avec collie pair. Un appareil appairé dispose d'un contrôle total ; quiconque sur votre tailnet peut joindre l'URL a donc tout de même besoin d'un téléphone appairé au préalable. Sans COLLIE_TRUSTED_USER, le bridge affiche un avertissement TRUSTED_USER, car chaque connexion au tailnet peut accéder à l'écran d'appairage. Pour restreindre davantage l'accès :

# in your .env
COLLIE_TRUSTED_USER=you@example.com           # your tailnet login — Collie rejects anyone else
COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net    # only behind your OWN proxy; on a tailnet `collie
                                              # start` discovers this for you

Le fichier de configuration

Chaque paramètre de Collie peut être écrit dans un fichier TOML. Écrivez-en un avec chaque paramètre et sa valeur par défaut :

collie config init

Cela écrit ~/.collie/config.toml, la déclaration propre à la machine, et affiche le chemin. Chaque clé y est commentée, donc le fichier tel quel ne modifie rien : décommentez une clé et redémarrez. Exécutez plutôt collie config init --instance pour écrire config.toml à côté de votre .env, ce qui surcharge le fichier de la machine pour cette seule instance.

Le fichier d'instance l'emporte clé par clé, jamais fichier par fichier : une clé absente conserve la valeur du fichier machine. Il n'existe pas de config.<instance>.toml, car sur une installation gérée par Herdr, le répertoire de configuration est déjà propre à l'instance, et sur une installation binaire, il s'agit de ~/.config/collie. Une deuxième instance de Collie sur un même hôte place donc ses propres paramètres dans son propre répertoire de configuration, voir docs/deployment.md → Plusieurs instances de Collie sur un même hôte. Un fichier .collie/ situé dans le répertoire d'un projet n'est pas lu du tout.

Trois verbes pilotent le fichier :

1. 01
   collie config init écrit un fichier commenté contenant chaque paramètre et sa valeur par défaut.
2. 02
   collie config check valide les deux fichiers qui seraient lus, ou un fichier que vous désignez.
3. 03
   collie config show affiche les deux chemins ainsi que chaque paramètre avec sa valeur et sa provenance.

L'ordre de priorité applique les valeurs par défaut, puis ~/.collie/config.toml, puis <config-dir>/config.toml, puis l'environnement du processus, qui inclut votre .env. collie config show indique le gagnant pour chaque clé à la fois ; la question « pourquoi mon intervalle de scrutation est-il toujours à 1500 » trouve ainsi sa réponse en une seule ligne.

Une clé invalide n'interrompt jamais le bridge. Une clé inconnue ou un type incorrect est une anomalie que collie config check affiche et que collie doctor signale, et cette clé seule se rabat sur la valeur définie par l'environnement. Toutes les autres clés du fichier continuent de s'appliquer.

Collie lit config.toml uniquement au démarrage. Exécutez collie restart après l'avoir modifié.

Remarque. Un fichier contenant [push] vapid_private ou [stt] stt_key doit être en mode 600, exactement comme votre .env. Si Collie ne peut pas en restreindre les droits d'accès, ces clés seules sont ignorées et collie doctor le signale.

L'environnement reste prioritaire

Collie charge la configuration depuis un fichier .env situé dans ~/.config/collie. Si Herdr gère l'installation, le CLI interroge Herdr pour obtenir le répertoire de configuration du plugin (généralement ~/.config/herdr/plugins/config/herdr.collie). Les deux chemins se résolvent de manière cohérente dans les commandes du CLI, le service lit donc le fichier initialisé ici :

mkdir -p ~/.config/collie && cp .env.example ~/.config/collie/.env

# on a Herdr-managed install, seed Herdr's plugin config dir instead:
cp .env.example "$(herdr plugin config-dir herdr.collie)/.env"

Les chemins ci-dessous utilisent ~/.config/collie/…. Sur une installation gérée par Herdr, remplacez ce préfixe par $(herdr plugin config-dir herdr.collie).

Collie lit .env uniquement au démarrage. Exécutez collie restart après l'avoir modifié.

Le fichier .env.example liste toutes les options, tout comme collie config init --print.

Il inclut COLLIE_PORT, COLLIE_SERVE_MODE=http (pour Headscale ou les domaines .internal) et COLLIE_SERVE_PORT (pour exposer HTTPS sur un autre port que :443 ; voir docs/deployment.md → Plusieurs instances de Collie sur un même hôte). Le CLI lit les paramètres de serve pour configurer tailscale serve, au lieu de les transmettre au bridge.

Contenu de chaque section

Le fichier de configuration regroupe chaque paramètre sous une section [section]. Le nom d'environnement d'une clé est COLLIE_ suivi de la clé en majuscules ; ainsi, [bridge] poll_ms devient COLLIE_POLL_MS.

Les agents durables qu'un processus Collie exécute à côté de son multiplexeur ne figurent pas dans config.toml. Chacun correspond à une entrée dans sources.json, dans le même dossier que .env (Agents durables). | stt | reconnaissance vocale, absente tant que collie stt setup n'a pas été exécuté |

Pour lire l'historique de plusieurs répertoires personnels d'agents, fournissez une liste séparée par des virgules dans COLLIE_TRANSCRIPT_ROOT.

docs/deployment.md couvre les domaines personnalisés et les proxys inverses. Collie applique une politique de même origine (same-origin policy) ; tout nom d'hôte personnalisé ou terminateur TLS externe doit donc figurer explicitement dans la liste d'autorisation :

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Sans ce paramètre, l'interface utilisateur se chargera sous la forme d'une page blanche. Consultez Dépannage pour plus de détails.

Vos propres commandes slash

Placez les commandes propres à la machine, telles qu'un plugin Herdr /fork-in-herdr ou un /deploy personnalisé, dans commands.toml. C'est l'un des six fichiers de configuration qui partagent le même lecteur et le même modèle de chargement :

Ces fichiers ne sont pas modifiés par le fichier de configuration. Ils partagent le répertoire de l'instance config.toml, ils conservent leurs propres formats et leur propre rechargement à chaud, et rien ne les y fusionne.

Toute ligne comportant l'indicateur activé requiert une confirmation en deux étapes avant son exécution. Les modifications apportées à l'un de ces fichiers prennent effet sans redémarrer le service. Si Collie rejette une ligne, journalctl --user -u collie -n 20 affiche le numéro de la ligne et l'erreur.

cp commands.toml.example ~/.config/collie/commands.toml

[[commands]]
scope = "omp"                # optional; omit for every pane
command = "/fork-in-herdr"
description = "Fork this conversation into a new herdr tab"

[[commands]]
scope = "claude"
command = "/statusline"
description = "Set the status line"
bar = true
bar_label = "Status"

Un volet correspondant à vos lignes configurées affiche uniquement ces lignes. La ligne la plus spécifique l'emporte, comme documenté dans ADR 0018.

Pour vérifier, ouvrez un volet et appuyez sur / ; vos lignes apparaissent sur le premier écran.

Placer une commande sur la rangée d'actions

bar = true place également la ligne sur la rangée d'actions, l'unique rangée de boutons située au-dessus du clavier. Une ligne de barre reste une ligne de palette ordinaire, elle apparaît donc sur les deux surfaces. bar_label est le texte du bouton et prend par défaut le nom de la commande sans son slash.

La rangée d'actions est un bandeau continu situé au-dessus du clavier. Les commandes propres à Collie se trouvent directement sur le bandeau : Touches, Saisie, Rapide, Agent et la roue crantée d'affichage. Les commandes propres au harnais en cours d'exécution se trouvent à côté, dans une section teintée de la couleur du harnais, afin d'identifier immédiatement les boutons qui écrivent dans l'agent. Un glissement latéral fait défiler le bandeau ; aucun bouton n'est masqué.

Chaque harnais fournit ses propres boutons, dans cet ordre :

Codex, Grok et Antigravity n'ont pas de bouton Effort, car leur sélecteur /model définit aussi l'effort de raisonnement. Un /effort seul dans Grok n'ouvre aucun sélecteur.

pi et opencode n'ont pas de commande d'effort. pi garde ce réglage dans /settings, une modale que le pavé de touches ne peut pas piloter utilement, et opencode fait défiler ses variantes sur une touche.

opencode nomme deux boutons à sa façon : Model envoie /models et Resume envoie /sessions. Son Compact fonctionne dès que la session contient un tour, car opencode ne propose /compact qu'à ce moment-là.

Le bouton Arborescence d'omp se trouve entre Compacter et Reprendre. Il ouvre l'arborescence de session propre à omp dans le miroir, un sélecteur qui permet de revenir à n'importe quel point antérieur de la session. La même commande, /tree, se trouve également dans la palette de commandes d'omp.

Chaque bouton de harnais envoie sa commande brute. Modèle envoie /model, et le sélecteur de modèle propre à l'agent prend le relais dans le panneau. Collie ne conserve aucune liste de noms de modèles, car cette liste appartient au harnais et change sans préavis. L'effort fonctionne de la même manière.

Vos lignes de barre remplacent le segment de harnais par défaut pour les panneaux qu'elles ciblent, et le laissent intact partout ailleurs. La palette Agent est une surface distincte et une ligne de barre ne l'efface jamais (ADR 0043).

Une valeur bar_label de plus de 12 caractères est raccourcie et le bouton apparaît toujours. Une valeur bar qui n'est ni true ni false supprime cette seule ligne, de la même manière qu'une valeur confirm incorrecte.

La ligne envoie la commande pendant que l'agent est occupé, tout comme la palette de commandes. La coche n'apparaît que lorsque le panneau a reçu le texte.

Un bouton Commuter se trouve à l'extrémité droite du bandeau et ouvre le sélecteur de panneaux. Il affiche uniquement le symbole des calques, derrière un filet, et ne comporte aucun mot. Un glissement vers le haut, n'importe où sur le bandeau, ouvre le même sélecteur. Un glissement latéral fait défiler le bandeau.

Le repère d'agents situé à gauche du bouton Fichiers compte les sous-agents en cours d'exécution du volet. Pour omp et Gentle Shell, il ne compte leurs tâches de fond que lorsque le Chat du volet est ouvert sur un téléphone ; la vue Écran ne les compte pas.

Tant que la zone de texte contient du texte ou une pièce jointe, une croix se trouve également à l'extrémité droite du bandeau, à gauche du bouton Switch. Un appui vide la zone ainsi que son brouillon enregistré, et n'envoie rien au panneau. La croix devient alors Annuler, ce qui rétablit le texte et les pièces jointes. Annuler reste disponible jusqu'à votre action suivante : une frappe au clavier, un ajout de pièce jointe, un envoi, un appui sur un autre bouton du bandeau ou la sortie du panneau. Faire défiler le bandeau le conserve.

Gaucher ? Définissez Paramètres → Apparence → Main sur Gauche. La ceinture s'inverse : le bouton Switch et la croix passent à son extrémité gauche, toujours au-dessus de Send, et Keys devient le bouton le plus à droite, le reste défilant vers la gauche. Send et Attach passent à gauche de la zone de réponse. Le réglage s'applique par appareil et prend effet à la prochaine ouverture d'un panneau.

Pour vérifier, ouvrez un panneau exécutant Claude Code, Codex, pi ou omp ; le segment teinté se trouve à droite de la rangée au-dessus du clavier. Désactivez ce segment par appareil dans Paramètres → Apparence → Raccourcis du harnais ; les commandes propres à Collie restent affichées.

Arrêter un tour

Un bouton Arrêter se trouve au début du bandeau, avant les autres boutons de Collie, pour rester visible sans défilement. Il apparaît pour chaque agent dont le profil de harness définit une touche d'arrêt, et il est grisé quand rien ne tourne. Il conserve sa place et sa taille, pour que les autres boutons ne bougent jamais au début ou à la fin d'un tour. Appuyer sur le bouton grisé ne fait rien et n'envoie rien. Un agent sans touche d'arrêt n'a pas de bouton. Stop ne tape rien et n'envoie aucun message. Il appuie sur la propre touche d'arrêt de l'agent, une seule fois, et vous indique ce qui s'est passé.

Un Stop nécessite deux appuis. Le premier appui arme le bouton : le texte devient Arrêter ? et le bouton conserve sa taille. Appuyez à nouveau dessus dans les quatre secondes pour arrêter le tour. Un second appui immédiat, sous 0,4 seconde, est considéré comme le même contact et est ignoré. Si vous attendez, l'armement expire et rien n'est actionné. L'armement expire aussi si vous ouvrez un autre panneau, et le bouton devient grisé quand le tour se termine. Pendant que le second appui est en cours de traitement, le bouton n'en accepte aucun autre, de sorte qu'un troisième appui rapide ne peut pas déclencher un second Stop.

Le choix de la touche qui arrête un tour appartient au harness, et le profil du harness la conserve. La plupart des agents s'arrêtent avec Échap, certains avec Ctrl+C, et d'autres nécessitent deux fois Échap. C'est le profil qui décide, pas cette page.

Après l'envoi de la touche, Collie relit l'écran pendant une durée maximale de trois secondes et affiche l'un de ces trois messages sous la boîte :

Si la touche d'arrêt a ouvert une boîte de dialogue à la place, Collie vous l'indique et vous renvoie vers sa carte.

Certains agents, dont OMP, replacent un message en file d'attente dans leur zone de saisie lorsque vous interrompez le tour. Quand Collie l'y détecte juste après la touche, le reçu l'indique, par exemple « Interrompu. 1 message en file d'attente est de retour dans l'agent en tant que brouillon. » Dans le Chat, le message se déplace vers une carte De retour dans la boîte. Les messages revenus ensemble partagent une même carte.

La carte comporte deux boutons, et tous deux relisent d'abord la zone. Envoyer envoie le brouillon uniquement lorsque le tour est inactif et que la zone contient exactement ce texte. Abandonner vide la zone uniquement lorsqu'elle contient encore ce texte ; si vous l'avez modifié, Abandonner retire la carte et n'appuie sur rien. Tant que le brouillon reste présent, tout nouveau message est refusé, et le refus vous renvoie vers la carte.

Collie refuse d'agir avant d'appuyer si l'action risque de poser problème :

• —
  Une boîte de dialogue est ouverte. Échap répondrait à cette boîte de dialogue. Répondez-y plutôt sur sa carte.
• —
  La boîte contient votre texte, et la touche d'arrêt de ce harness l'effacerait. Effacez la boîte ou utilisez le bouton Clear sur le pavé Keys, puis appuyez de nouveau sur Stop.
• —
  Collie ne peut pas lire ce panneau. Il n'envoie aucune touche sur un écran qu'il ne peut pas lire. Cela concerne aussi les écrans où Collie ne peut pas déterminer si un tour est en cours.
• —
  Le tour était déjà terminé. Il n'y avait rien à arrêter, donc aucune touche n'a été actionnée.
• —
  Cette machine ne peut pas encore effectuer d'arrêt depuis le téléphone. Sur un crew, la machine qui exécute le panneau utilise une version plus ancienne de Collie. Mettez-la à jour, puis arrêtez.

Si aucune réponse ne revient d'une machine du crew à temps, Collie vous le signale. Le Stop a peut-être été pris en compte, vérifiez donc le panneau avant d'appuyer à nouveau sur Stop.

Un Stop provient toujours de votre appui. Un message walky talky, un hook, la ligne de commande ou une action en file d'attente n'en déclenchent jamais. Sur un crew, la machine qui exécute le panneau appuie sur la touche, lit l'écran et renvoie l'accusé de réception via le lead.

Un programme exécuté en tant qu'agent durable conserve le Stop qu'il possédait déjà. Il interrompt le tour qu'il désigne, avec son propre reçu, et n'utilise pas l'armement.

Vider le champ

Le bouton Effacer situé au bout de la rangée de puces sur le panneau Keys vide le champ de saisie du harness d'un seul appui, sans armement. Collie appuie sur la touche de suppression propre au harness autant de fois que le texte l'exige, relit le champ et vous indique dans une notification au-dessus de la ceinture si le champ est vide ou pourquoi il ne l'est pas. Le bouton est grisé lorsque le champ est vide, qu'une boîte de dialogue est ouverte ou que la liaison est interrompue, et si le champ ne se vide pas, Collie laisse ce qui reste en l'état sans appuyer à nouveau.

Après un Clear, la notification propose Restaurer pendant deux minutes. Un appui réécrit le texte dans le champ, sur une seule ligne et sans Entrée, pour ne rien envoyer. Restore disparaît dès que vous tapez à nouveau dans le champ ou que vous ouvrez un autre panneau. Le pont conserve le texte effacé en mémoire avec le reçu du Clear, et ne l'écrit jamais dans un journal ni sur le disque.

Vos propres préréglages de touches

Vous pouvez remplacer la ligne Préréglages du tiroir Keys dans keys.toml, situé à côté de commands.toml :

cp keys.toml.example ~/.config/collie/keys.toml

[[keys]]
scope = "claude"             # optional; omit for every pane
label = "Yes"
keys = ["Down", "Enter"]     # several chords go out as one batch

Lorsqu'un panneau correspond à vos lignes définies, il affiche uniquement vos préréglages au lieu des boutons par défaut Ctrl C/D/U/R/L/Z (ADR 0018). Ces lignes vous appartiennent en tant qu'opérateur et s'appliquent à tous les téléphones. Le pavé au-dessus (Échap, les flèches, Entrée/Tab/Espace, les modificateurs) n'est pas défini ici : chaque téléphone organise le sien, voir la section suivante.

Les accords utilisent la syntaxe de herdr, pas celle de tmux :

Pour vérifier, ouvrez un volet et appuyez sur Touches → Préréglages pour afficher les nouveaux boutons. Si Collie rejette une ligne, consultez journalctl --user -u collie -n 20 pour le détail de l'erreur.

Votre propre pavé de touches

Vous pouvez réorganiser le pavé Touches. Ouvrez Touches et touchez le crayon à côté de l'étiquette :

1. 01
   Touchez le crayon à côté de Touches. Un grand panneau s'ouvre au-dessus du volet.
2. 02
   Glissez une touche vers un autre emplacement, ou touchez-la et utilisez les quatre boutons fléchés.
3. 03
   Touchez un + en pointillés pour ajouter une touche dans une case libre, ou sélectionnez une touche et touchez Modifier ou Supprimer.

Le pavé est une grille de 7 colonnes. Une touche occupe une case et peut être plus large (1, 2 ou 3 colonnes) et plus haute (1 ou 2 lignes). Sélectionnez une touche et touchez Largeur ou Hauteur pour la redimensionner. Elle s'étend vers la droite et vers le bas. Une taille qui recouvrirait une autre touche, ou qui dépasserait du pavé, apparaît estompée, et la toucher indique quelle touche fait obstacle. Collie ne déplace jamais une seconde touche à votre place. Ajouter une ligne ajoute une ligne en bas, jusqu'à huit au total. Les modifications apparaissent aussitôt dans le dock. Collie conserve votre pavé dans ce navigateur ; un autre navigateur démarre donc avec le pavé par défaut tant que vous n'y partagez pas une disposition. La disposition par défaut correspond au pavé précédent, avec la barre d'espace sur trois cases de large et Entrée à l'extrémité gauche de la seconde ligne :

Esc    Tab    Shift  Ctrl   Alt    Up     ^C
Enter  Space (3 wide)        Left   Down   Right

Glisser une touche déplace l'ensemble de sa surface. Déposez-la sur une touche de même taille pour les échanger. Déposez-la sur tout autre élément qui fait obstacle : le contour cible devient gris et pointillé, une ligne indique quelle touche bloque, et la touche revient à sa place. Un bouton fléché saute les touches qui font obstacle et s'arrête au prochain emplacement disponible ; s'il n'y en a aucun, il reste inactif.

Une touche envoie une combinaison de trois modificateurs au maximum plus une touche, par exemple Ctrl+Alt+Shift+T. Elle peut aussi envoyer une séquence courte allant jusqu'à quatre étapes, par exemple Ctrl+B puis C. Une séquence part dans l'ordre, en un seul appel. Dans le constructeur de touches, choisissez Caractère, Nommée ou Touches F pour ces cas. Choisissez Modificateur pour créer une touche rémanente Ctrl, Alt ou Shift semblable à celles du pavé par défaut : touchez-la une fois pour armer la touche suivante, une deuxième fois pour la maintenir enfoncée, une troisième fois pour la relâcher. Une touche de modificateur est autonome : elle n'a donc ni étapes ni nom. Chaque touche suit le même circuit que les touches intégrées : elle patiente quand le volet est verrouillé ou hors ligne, une touche pouvant arrêter un programme (Ctrl+D, Ctrl+Z ou une séquence contenant Ctrl+C) demande confirmation par un second appui, et une touche que votre multiplexeur ne peut pas envoyer apparaît grisée.

Les codes des versions antérieures s'importent toujours, avec chaque touche sur une case. Si Échap, Entrée ou une flèche ne figure pas sur votre pavé, une ligne discrète le signale, avec Remettre. Le préréglage Préfixe (Ctrl+B) envoie le préfixe Ctrl+B, ce qui convient à un tmux tournant dans le volet. Le préréglage Navigation contient Début, Fin, Page préc. et Page suiv., que Herdr ne peut pas envoyer ; ils sont donc grisés sur un volet Herdr (ADR 0092).

Vos propres réponses rapides

Vous pouvez personnaliser les phrases du dock Rapide dans quick-replies.toml :

cp quick-replies.toml.example ~/.config/collie/quick-replies.toml

[[replies]]
scope = "claude"             # optional; omit for every pane
title = "confirm"
items = ["yes", "no"]        # sent verbatim, one per button

Lorsqu'un panneau correspond à vos règles, vos groupes remplacent ceux par défaut (ADR 0018). Les phrases par défaut sont en anglais (yes, commit and push, drastically simplify).

Utilisez ce fichier pour travailler dans d'autres langues, ou pour envoyer des mots comme approve à des environnements de test spécifiques. Définir scope = "shell" cible les volets shell standards, qui ne reçoivent sinon que y/n.

Pour vérifier, ouvrez un volet et appuyez sur Rapide pour voir vos groupes. Si le chargement d'une ligne échoue, journalctl --user -u collie -n 20 affiche l'erreur.

Vos propres lanceurs

Un appui exécute une commande que vous avez déclarée, dans launchers.toml à côté de keys.toml :

cp launchers.toml.example ~/.config/collie/launchers.toml

[[launchers]]
command = "htop"             # required; the shell line, typed verbatim into the fresh shell
label = "Top"                # optional; defaults to the first word of command
# cwd = "~/dev/collie"       # optional; absent means "here" — see below

L'endroit où la ligne s'ouvre dépend de l'endroit d'où vous la démarrez, pas de la ligne elle-même. Depuis le Nouvelle page (Shell, puis la ligne dans le sélecteur Command), Start crée un nouvel Space qui porte le nom de son dossier, et le libellé de la ligne nomme l'onglet. Depuis un volet (le panneau de sélection accessible en balayant vers le haut), appuyer ouvre un nouveau onglet dans le propre Espace de ce volet, à côté, qui porte le nom de la ligne.

Dans les deux cas, le pont saisit command dans le nouveau shell et envoie Entrée. La commande gère sa propre durée de vie : une commande qui se ferme d'elle-même emporte le Space ou l'onglet avec elle, et htop reste actif jusqu'à ce que vous le quittiez.

cwd est l'emplacement où s'ouvre ce nouvel espace ou onglet. Définissez un dossier fixe pour une ligne (comme le fait htop ci-dessus) et il prend la priorité quel que soit l'endroit où vous appuyez sur la ligne.

Si vous l'omettez, cela signifie « ici » : le tableau de bord l'ouvre dans votre dossier personnel, un volet l'ouvre dans celui de ce volet cwd. Une ligne sans cwd vous suit d'un checkout à l'autre au lieu de toujours s'ouvrir à la racine de l'un d'eux.

Ce fichier et les lignes ajoutées depuis un téléphone (ci-dessous) constituent la liste d'autorisation. POST /api/launch n'accepte qu'un command correspondant exactement à l'une de ces lignes, un identifiant d'agent issu de la propre liste de la machine (la machine tape la commande de cet agent elle-même), ou un simple shell. Les modifications s'appliquent immédiatement sans redémarrage, mais un onglet déjà ouvert ne relit les lignes qu'à son prochain chargement.

Deux clés optionnelles fournissent au téléphone plus d'informations sur une ligne :

[[launchers]]
command = "claude-danger"
label = "Claude Code, no prompts"
# The agent that reads the row: it is listed under Agent with that agent's mark.
harness = "claude"
# The line skips permission prompts, but an alias hides its flags.
no_prompts = true

Vos lignes apparaissent à trois endroits :

• —
  Sur la page New (appuyez sur + Nouveau sur le tableau de bord). Le sélecteur en haut affiche Agent | Shell. Une ligne avec harness se trouve dans la liste déroulante Agent. Une ligne sans harness se trouve dans la liste déroulante Commande, qui est celle sous Shell.
• —
  Dans une section Launch sur le tableau de bord. Elle se replie comme Spaces.
• —
  Dans une section Launch du volet de sélection (balayez vers le haut depuis un panneau).

Sur la page New, une ligne sans cwd s'exécute dans le dossier que vous y indiquez, et une ligne avec un dossier fixe affiche ce dossier à la place du champ. Une ligne ne démarre jamais dans un worktree ; choisissez un agent ou Shell pour cela. Une ligne avec un dossier fixe l'affiche, raccourci sous home ; une ligne sans cwd indique « here » dans le sélecteur (le tableau de bord sous-entendant déjà home, il n'affiche rien ici). Si vous ne déclarez aucune ligne, aucune des deux sections n'apparaît.

Dans une crew (plusieurs machines, un lead relié au téléphone), chaque machine lit sa propre copie de ce fichier : une ligne se lance sur la machine dont vous avez touché le tableau de bord ou le volet, pas sur le lead.

Le sélecteur Agent sur la page New correspond à la liste propre à Collie : Claude Code, Codex, opencode, pi, omp, Grok, Hermes, Kiro, Muse et Antigravity. Kiro démarre en conservant les autorisations d'outils telles que vous les avez configurées. Un agent absent du PATH de connexion de la machine reste dans la liste, désactivé, avec la mention « not installed ». Pour un autre agent de terminal, déclarez une ligne pour lui comme ci-dessus : il apparaît dans le sélecteur Commande sous Shell, démarre dans un panneau comme n'importe quelle commande, et Collie n'affiche aucun état pour lui.

Pour vérifier, rechargez le tableau de bord et regardez sous le herd. Si le chargement d'une ligne échoue, journalctl --user -u collie -n 20 affiche l'erreur.

Lanceurs ajoutés depuis un téléphone

Un téléphone peut ajouter ses propres lignes sur une machine. Elles sont conservées dans le dossier d'état de cette machine, dans launchers-added.json, jamais dans launchers.toml, et ne sont jamais copiées vers une autre machine.

Sur la page New, appuyez sur Ajoutez les vôtres sous la liste déroulante Agent ou sous la liste déroulante Commande. Cela ouvre la page /new/add pour la machine qui y est sélectionnée. Choisissez Agent ou Commande en haut. Pour un agent, deux approches existent : une recipe (un harnais, des puces d'options, et la ligne exacte que Collie saisira) et Écrire une commande. Une ligne de commande s'écrit toujours à la main. Ajouter revient à la page New avec la nouvelle ligne sélectionnée. Sous le formulaire, Ajouté sur cette machine liste chaque ligne qu'un téléphone y a ajoutée, avec Renommer et Supprimer, ainsi que les lignes issues de launchers.toml avec un verrou et sans actions. Comment fonctionne l'ajout ouvre une courte explication contenant le chemin launchers.toml de cette machine et un exemple de ligne que vous pouvez copier.

[phone]
adds = true          # default true: a phone may add rows built from a recipe
free_text = false    # default false: a phone may also add a line typed by hand
run = true           # default true: a phone may run a one-off command, and run it again from history

Placez la table [phone] n'importe où dans launchers.toml. Une valeur qui n'est ni true ni false est lue comme false. Le bridge applique les réglages : un ajout refusé ne modifie rien, et une ligne désactivée par un réglage cesse immédiatement de démarrer. La ligne reste dans le fichier ; réactiver le réglage la rétablit donc.

Une recipe associe un agent et des puces d'options issues de la table propre au bridge, par exemple Claude Code et « Skip permission prompts ». Le téléphone envoie uniquement les identifiants, et le bridge construit la ligne. Chaque puce a été lue depuis le --help propre à cet agent :

Une ligne libre, comme un alias tel que claude-danger ou une simple htop, n'est possible qu'avec free_text = true. Sans cela, Écrire une commande affiche une seule ligne désactivée, "Désactivé sur" la machine, et Ajouter reste désactivé. Avec cela, Vérifier la ligne affiche la ligne avec chaque caractère masqué écrit sous forme de code (par exemple ⟨U+200B⟩) avant que Ajouter ne s'active. Elle compte au maximum 200 caractères, et le bridge refuse les caractères de contrôle, les séparateurs de ligne ou de paragraphe ainsi que les contrôles bidi, à la fois lors de l'ajout et à chaque lecture.

Une machine conserve au maximum 20 lignes ajoutées. Si une ligne a le même contenu qu'une ligne dans launchers.toml, la ligne de launchers.toml l'emporte. Chaque ligne ajoutée enregistre l'appareil associé qui l'a ajoutée. Révoquer cet appareil supprime ses lignes, depuis le téléphone ou avec collie devices revoke, et le journal d'audit enregistre chaque ajout, renommage et suppression.

Attention. Une ligne qui ignore les invites de permission porte un badge "Aucune invite". Chaque appareil demande confirmation une fois avant de lancer cette ligne pour la première fois, et affiche la commande, le dossier et la machine. Définissez adds = false pour désactiver toutes les lignes ajoutées par un téléphone sur une machine.

Accéder à un agent durable (expérimental)

Chaque agent durable qu'un processus Collie exécute à côté de son terminal correspond à une entrée dans sources.json, écrite par collie durable attach (Agents durables). Les trois premières variables ci-dessous représentent l'ancienne forme, pour une instance uniquement durable (COLLIE_MUX=durable) qui pilote un seul agent durable, nommé default. Définissez le socket, ou l'URL avec son jeton, jamais les deux.

Définir les deux, une URL sans jeton, ou un jeton sans URL constitue une erreur de configuration : l'instance démarre et affiche l'agent durable comme injoignable avec cette raison. Sur https, chaque interrogation est une requête facturée, Collie interroge donc toutes les 2 s lorsqu'un téléphone observe et toutes les 10 s dans le cas contraire. Agents durables détaille ce que chaque méthode bloque, et ce qu'elle ne bloque pas.

Starters d'un agent durable (expérimental)

Un agent durable liste ses starters sur la page New que vous ouvrez depuis celui-ci, sous Nouvelle conversation. Un starter est une manière nommée de démarrer une conversation, comme une revue de code. Il ne prend aucun texte : vous appuyez dessus, et l'agent durable décide quoi lancer. La nouvelle conversation s'ouvre sous la forme d'un panneau. Un appui répété avec le même identifiant de requête ouvre la même conversation et ne démarre rien de nouveau, et si l'agent durable ne répond pas, Réessayer renvoie le même identifiant de requête. Un agent durable inaccessible ne liste aucun starter. Cette fonctionnalité est expérimentale et peut changer lors de toute version mineure.

Commandes ponctuelles et leur historique

Un téléphone peut également exécuter une commande unique qui n'est pas un lanceur. Collie ouvre un shell dans le dossier indiqué et y saisit la ligne, de la même manière qu'il démarre une ligne de lanceur. La ligne suit la même règle qu'une ligne libre : 200 caractères au maximum, et aucun caractère de contrôle, séparateur ou bidi. Une commande ponctuelle ne démarre jamais sur une nouvelle branche.

Cette option est activée par défaut, car un téléphone associé peut déjà ouvrir un shell et y taper du texte. Définissez run = false dans la table [phone] pour retirer le raccourci sur cette machine.

Sur la page New, basculez vers Shell. La liste déroulante Commande se termine alors par deux ajouts : un groupe Récents, qui liste les lignes de l'historique de cette machine, et Tapez une commande…. Choisissez Tapez une commande… et un champ texte apparaît juste sous la sélection. Tapez la ligne et appuyez sur Démarrer (ou sur la touche Entrée, étiquetée Exécuter). La ligne au-dessus de Démarrer indique ce qui s'exécute et où, par exemple "Exécute htop dans ~/projects sur bluefin". Le sélecteur de worktree reste désactivé pour une ligne ponctuelle.

Avant la première exécution, Collie demande à la machine de vérifier la ligne. La vérification n'exécute rien et ne conserve rien. Si la ligne comporte un flag qui ignore les invites de permission, comme --dangerously-skip-permissions, ce téléphone demande confirmation une fois avant de démarrer, tout comme pour une ligne avec le badge "Aucune invite". Si la ligne enfreint la règle ci-dessus, une notification indique la raison et rien ne s'exécute.

Choisissez une ligne dans Récents pour la réexécuter. Le champ Dossier se remplit avec le dossier dans lequel cette ligne a tourné pour la dernière fois, sauf si vous avez modifié le dossier vous-même. Lorsqu'une ligne de Récents est sélectionnée, Retirer de l'historique et Effacer l'historique apparaissent sous le menu déroulant. Effacer l'historique demande confirmation d'abord. La ligne Recommencer en haut de la page répète également une exécution ponctuelle. Avec run = false, les lignes de Récents restent dans la liste mais sont désactivées, et Tapez une commande… disparaît. Une machine antérieure à la version 1.19.0 n'affiche ni l'un ni l'autre.

Chaque commande lancée est conservée dans le dossier d'état de cette machine, dans commands-recent.json. Le fichier conserve au maximum 12 lignes, les plus récentes en premier, avec le dossier dans lequel chacune a tourné pour la dernière fois. Réexécuter une ligne la replace en haut. Une ligne semblant contenir un secret, tel que TOKEN=abc deploy, une URL avec mot de passe, ou un mot comme token, secret ou password, s'exécute quand même mais n'est pas conservée. Vous pouvez supprimer une ligne ou effacer la liste depuis le téléphone. Avec run = false, la liste est toujours visible, mais aucun de ses éléments ne démarre. Dans une crew, chaque machine conserve sa propre liste, et rien n'est copié d'une machine à l'autre.

La liste n'est pas une permission. Démarrer une ligne depuis celle-ci constitue une nouvelle exécution ponctuelle, qui nécessite un appareil associé ; dissocier ou révoquer un appareil laisse donc la liste intacte. Le journal d'audit enregistre le premier mot d'une commande ponctuelle et sa longueur, jamais la ligne entière, car une ligne peut contenir un secret que vous avez saisi.

Vos propres polices

La police de l'interface est un paramètre propre à chaque appareil. Sous Paramètres → Apparence → Police, vous pouvez choisir entre System, Space Grotesk, Aldrich (par défaut), IBM Plex Sans, Geist et Atkinson Hyperlegible Next. Un thème qui spécifie une fonte l'inscrit ici une seule fois, lorsque vous choisissez le thème. Vous pouvez ajouter des polices personnalisées dans theme.toml, le quatrième fichier de configuration :

cp theme.toml.example ~/.config/collie/theme.toml
mkdir -p ~/.config/collie/fonts
cp departure.woff2 ~/.config/collie/fonts/

[[font]]
family = "Departure Mono"    # the picker's label AND the CSS family
file   = "departure.woff2"   # a bare name inside fonts/, woff2 only
weight = "400 700"           # optional

Les polices personnalisées s'ajoutent à la liste intégrée plutôt que de la remplacer (ADR 0033), contrairement au comportement de commands.toml et des autres fichiers de configuration. Comme les polices ne déclenchent pas d'actions, il n'y a rien à masquer.

Elles apparaissent sous les entrées fournies par défaut, et chaque appareil client sélectionne la sienne.

Trois comportements à noter :

• —
  Décalage de mise en page au premier chargement. Les polices personnalisées ne disposent pas de polices de secours ajustées aux métriques, ce qui provoque un léger décalage de mise en page au chargement initial. Les polices intégrées évitent cela, car leurs polices de secours sont générées au moment du build.
• —
  Délai de chargement à froid. Un chargement à froid récupère le fichier avec un court délai ; un client en cache effectue le rendu immédiatement.
• —
  Interface uniquement. La police sélectionnée s'applique uniquement à l'interface de Collie. Le miroir du terminal, la transcription et le markdown rendu conservent leur propre typographie.
• —
  Actif au prochain rechargement. Les modifications ne nécessitent pas de redémarrage et prennent effet au rechargement suivant de la page. Les configurations non valides consignent des erreurs consultables via journalctl --user -u collie -n 20.

Vos propres règles de cache

Utilisez cache-rules.toml pour modifier une durée de vie du cache de prompt modifiée par votre fournisseur.

cp cache-rules.toml.example ~/.config/collie/cache-rules.toml

Collie fournit une règle par harnais et par fournisseur. Collie a extrait chaque règle depuis la page d'un fournisseur à une date enregistrée. Un fournisseur peut modifier cette valeur sans préavis. Une passerelle ou un proxy intermédiaire entre votre agent et le fournisseur peut également la modifier. Utilisez ce fichier pour remplacer les valeurs jusqu'à ce que Collie publie une mise à jour.

[[rule]]
id = "claude.api"
ttl_seconds = 3600
source_url = "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
retrieved = "2026-09-12"
note = "our gateway sends ttl 1h on every request"

Collie ne conserve une ligne que si les quatre règles sont respectées. id doit nommer une règle fournie. ttl_seconds doit être un entier compris entre 1 et 86400. source_url doit être une chaîne non vide. retrieved doit correspondre à une date YYYY-MM-DD valide et ne doit pas être postérieure à aujourd'hui. Les lignes non valides sont ignorées et consignées dans les journaux. Le reste du fichier s'applique toujours.

Deux règles supplémentaires définissent l'interprétation d'un fichier. Deux lignes avec le même id ne constituent pas une erreur : la dernière ligne l'emporte. Définir note comme une chaîne vide supprime toute la ligne ; omettez plutôt le champ.

Une ligne s'applique au niveau de la règle du palier, celle que son id désigne. La répartition par modèle sous ce palier suit cette règle, de sorte qu'une seule ligne couvre tous les modèles de ce palier.

Remarque. Vous pouvez modifier un nombre. Vous ne pouvez pas supprimer sa page source ni sa date de récupération. Le catalogue de règles requiert ces deux champs.

collie doctor vérifie trois éléments. cache-claims signale si personne n'a revérifié une règle fournie depuis 180 jours. cache-rules liste chaque ligne ignorée et la raison de son rejet. cache-env signale si vous avez défini ENABLE_PROMPT_CACHING_1H ou FORCE_PROMPT_CACHING_5M dans votre shell. Le pont s'exécute en tant que service distinct et ne peut pas lire l'environnement de votre agent. Recopiez ces variables Claude Code ici afin que le pont puisse les lire.

Voici les identifiants de règle que vous pouvez écrire.

Le compte à rebours du cache de prompt

Une pastille sur le panneau de chaque agent indique la durée restante pendant laquelle le cache de prompt de cet agent reste actif.

Chaque harnais pris en charge met en cache la conversation en cours. Les harnais facturent des tarifs réduits tant que ce cache reste actif. La pastille décompte le temps d'inactivité depuis la dernière requête de l'agent. Elle ne mesure pas l'âge total de la session. Chaque nouvelle requête réinitialise le minuteur.

Le sablier de la pastille indique l'état à l'aide de l'une des trois couleurs disponibles, et le nombre situé à côté reste gris. Le sablier est vert tant que la fenêtre est large, rouge pendant le dernier quart de celle-ci, et bleu dès que la fenêtre expire ou qu'un tour est facturé au tarif plein. La pastille affiche cold à l'état bleu, et <1m à la place des secondes lorsqu'il reste moins d'une minute.

Certaines actions vident le cache alors qu'il reste du temps : un basculement /model vers un autre modèle, une modification de l'effort, un compactage et /reload-plugins --force. La puce devient bleue dès que Claude Code consigne l'action dans sa transcription, et la fiche nomme l'action. opencode signale un compactage et un changement de modèle de la même manière.

La pastille se situe à l'extrémité droite de la deuxième ligne de l'en-tête du panneau, après l'espace de travail du panneau. Sur un crew, le nom de la machine figure à côté, sur la même ligne. Cliquez sur la pastille pour afficher la règle sous-jacente : l'identifiant de la règle, la page source du fournisseur et la date de récupération.

Remarque. Les valeurs sont des déclarations de fournisseurs associées à des dates enregistrées, et non des mesures en direct, sauf si la mention mesuré est présente. Claude Code consigne directement les fenêtres de cache dans sa transcription, donc les panneaux Claude font généralement l'objet de mesures directes.

Certains panneaux n'affichent aucune pastille. Ce comportement est normal. Un panneau n'affiche une pastille qu'après que son agent a terminé un tour. Collie n'émet aucune hypothèse avant la première mesure. Un panneau n'affiche rien si son harnais n'a pas d'adaptateur de journal, ou si son fournisseur ne publie aucune donnée de durée de vie.

Collie peut aussi envoyer des alertes push sur un téléphone avant qu'un cache n'expire. Une variable en contrôle le délai.

Ce paramètre contrôle uniquement l'alerte push. Il ne contrôle pas le moment où la pastille devient rouge. Le seuil rouge est fixé à un quart du TTL de chaque règle. Le push se déclenche selon la durée la plus courte entre ce paramètre et la moitié de la durée de vie du cache du panneau lui-même ; ainsi, un cache de cinq minutes (Codex, OpenCode, pi, omp) avertit environ deux minutes et demie avant d'expirer, même si cette durée est inférieure aux 300 secondes configurées. Pour activer les avertissements pour des panneaux spécifiques ou pour tous les panneaux, consultez voice-and-push.md.

Pièces jointes

Le trombone à côté de la zone de message téléverse un fichier sur l'hôte et insère son chemin dans votre message.

# in your .env
COLLIE_MAX_UPLOAD_MB=25              # default 10, floor 1, ceiling 512
COLLIE_UPLOAD_EXTRA_TYPES=rb,ex,zig  # bare extensions, no dot

Collie enregistre le fichier sous <state-dir>/uploads avec des permissions réservées au propriétaire et ajoute son chemin absolu à votre brouillon. L'agent le lit depuis ce chemin, car un terminal ne peut pas recevoir de fichier collé. Les fichiers téléversés sont supprimés 48 heures après leur écriture.

Deux types de fichiers sont acceptés et ils sont vérifiés différemment.

Les images sont identifiées par leurs octets de signature, jamais par leur nom ni leur type déclaré : png, jpg, gif et webp. Le format SVG est refusé délibérément, car il s'agit d'un balisage pouvant exécuter des scripts plutôt que d'une image.

Le texte est identifié par son extension, avec les octets en guise de veto : un fichier dont les 4 premiers Ko contiennent un octet NUL ou de contrôle parasite est refusé quel que soit son nom. La liste fournie comprend md, markdown, txt, json, jsonl, yaml, yml, toml, csv, tsv, log, xml, html, htm, css, js, jsx, mjs, cjs, ts, tsx, py, go, rs, sh, bash, sql, diff et patch.

Remarque. COLLIE_UPLOAD_EXTRA_TYPES ajoute uniquement des types de texte. Une image nécessite une signature pour être vérifiée ; aucun format binaire ne peut donc être ajouté de cette manière.

Augmenter COLLIE_MAX_UPLOAD_MB augmente deux autres limites. Le bridge lit l'intégralité d'un téléversement en mémoire avant de pouvoir le mesurer : un plafond élevé combiné à plusieurs téléversements simultanés consomme autant de mémoire. De plus, la limite de corps de requête du runtime s'applique à chaque route, pas seulement à celle du téléversement ; un plafond élevé permet donc à un corps volumineux d'atteindre n'importe quel gestionnaire, qui le refusera ensuite selon sa propre limite. Rien n'est supprimé avant l'expiration des 48 heures : le répertoire des téléversements contient au maximum ce qui a été envoyé en deux jours. N'augmentez ce nombre que par nécessité, pas par défaut.

Dans un crew, les deux paramètres sont propres à chaque machine, et la machine qui stocke le fichier est celle qui les applique. Le lead refuse un corps trop volumineux avant de le relayer pour préserver votre liaison montante, mais il le refuse selon son propre seuil. Définissez les mêmes valeurs sur chaque membre, sinon un pair refusera ce que son lead a laissé passer.

Dossiers favoris et récents

La page New liste les dossiers dans lesquels vous avez déjà lancé un élément, ce qui vous permet d'en sélectionner un au lieu de saisir un chemin.

Sous le champ Folder se trouvent deux listes destinées à la machine cible du démarrage. Récents contient les 8 derniers dossiers dans lesquels un élément a été lancé, du plus récent au plus ancien. Elle ne prend en compte que les démarrages réussis ayant spécifié un dossier, et ne liste jamais votre répertoire personnel, car un champ vide désigne déjà ce dernier. Le dossier propre d'une nouvelle branche n'y est pas ajouté, car il s'agit d'un nouveau checkout et non d'un emplacement où vous revenez.

Vous pouvez également saisir un chemin. ~/projects et /srv/www conservent leur sens usuel. Un nom sans / ou ~ au début, comme projects, est un dossier situé sous votre répertoire personnel, à l'image de cd projects dans un nouveau shell, et la ligne au-dessus de Start affiche le chemin complet (~/projects) avant que vous n'appuyiez. Un chemin contenant .. est refusé. Le dossier doit déjà exister sur la machine qui effectue le démarrage et doit être un répertoire. S'il est absent, rien ne démarre et un message au-dessus de Start indique "Il n'y a pas de dossier … sur cette machine." Collie vérifie uniquement lorsque vous appuyez sur Start, jamais pendant la saisie. Sur une crew, la machine sélectionnée vérifie son propre disque.

Appuyer sur une ligne remplit le champ Folder sans rien démarrer, ce qui vous permet de modifier votre choix ci-dessus. L'étoile à côté d'une ligne la déplace vers Favoris, jusqu'à 12 éléments, dans l'ordre où vous les avez marqués d'une étoile. Un second appui sur l'étoile la replace en haut de Recent.

Parcourir se trouve sous les deux listes. Un appui dessus liste les sous-dossiers du dossier présent dans le champ, ou de votre dossier personnel lorsque le champ est vide. Appuyez sur un dossier pour y entrer, et le champ s'actualise. Remonter, ou une portion du chemin au-dessus de la liste, permet de revenir en arrière. Un dossier qui est un dépôt Git porte un badge git. Utiliser ce dossier remplit le champ, à l'instar d'un appui sur une ligne de l'historique récent.

Lorsque le champ contient un chemin inexistant, tel que ~/src/plektra-, Browse s'ouvre sur le dossier existant le plus proche (~/src) et ne liste que les noms commençant par le reste (plektra-). Taper dans le champ affine donc la liste. Un chemin en dehors de votre dossier personnel affiche « Nothing to browse here ».

Browse lit uniquement les noms de dossiers situés sous votre dossier personnel, avec les limites de la vue Files. Il masque les dossiers préfixés d'un point sauf si vous tapez le point, ne liste jamais .git ni les dossiers d'état et de configuration propres à Collie, ne suit aucun lien sortant du dossier personnel et affiche au maximum 200 dossiers. Il ne crée rien et nécessite un appareil associé, tout comme Files.

La liste appartient à la machine, pas au téléphone. Chaque machine conserve la sienne dans folders.json dans son répertoire d'état, ~/.local/state/collie/folders.json sauf si COLLIE_STATE_DIR la déplace. Tous les appareils que vous utilisez voient la même liste, et le fichier n'apparaît qu'après le premier démarrage dans un dossier ou la première mise en favori. Les mêmes listes remplissent Autre dossier sous Nouveau worktree, où elles permettent de choisir le dossier qui recevra le dossier propre de la branche.

Dans un crew, chaque machine conserve les dossiers existants sur celle-ci, et la page affiche la liste de la machine sélectionnée. Une machine exécutant une version plus ancienne de Collie n'a pas de liste, et la page n'en affiche alors aucune pour elle. Browse liste également le disque de la machine sélectionnée, et une machine plus ancienne indique qu'elle nécessite une mise à jour.

Secret masking

Collie masque les formats de secrets connus dans le texte des panneaux avant qu'il n'atteigne votre téléphone.

# in your .env; the default is on
COLLIE_REDACT=off

Dans le fichier de configuration, il s'agit de [access] redact. Le masque préserve la largeur de ce qu'il masque, maintenant ainsi la disposition du miroir. Il ne repère que les formats à haute confiance ; les limites sont décrites dans Sécurité.

Dans une crew, le lead masque également le texte envoyé par ses membres, selon son propre réglage. Le texte d'un membre n'arrive démasqué sur votre téléphone que si le lead et ce membre activent tous deux COLLIE_REDACT=off.

Signaler un problème

Lorsque trois envois consécutifs sur un volet échouent pour une raison imputable à Collie, une carte au-dessus de la zone de réponse propose de le signaler. Paramètres → Système → Proposer un rapport en cas d'échec d'envoi désactive la carte pour cet appareil (stocké dans le navigateur, activé par défaut). L'option Signaler un problème du menu du volet et le bouton Signaler un problème sur la même carte dans Paramètres ouvrent toujours le volet.

Rien ne quitte le téléphone tant que vous n'appuyez pas sur Ouvrir sur GitHub ou Copier le rapport, et Collie ne conserve aucun jeton GitHub. Le contenu du rapport, et la façon de le lire avant l'envoi, se trouvent dans Dépannage.

Multi-session

Par défaut, une instance de Collie sert toutes les sessions Herdr qu'elle trouve.

COLLIE_MULTI_SESSION=on (par défaut) détecte et sert chaque session Herdr nommée sous la racine de votre configuration, commutable depuis l'en-tête. Définir COLLIE_MULTI_SESSION=off ne sert que la session Herdr principale. Chaque session Herdr détectée est accessible via la même URL, y compris les sessions privées ou les bacs à sable. Sécurité signale ce comportement comme un point de vigilance.

Fenêtres d'utilisation

Les points à côté du modèle indiquent vos limites de 5 heures et de 7 jours pour Claude et Codex, sans aucune configuration.

# turn every source off
COLLIE_ACCOUNT_WINDOWS=0
# turn on opencode and grok too, or name the ones you want
COLLIE_ACCOUNT_WINDOWS=all
COLLIE_ACCOUNT_WINDOWS=claude,codex

Collie lit votre fichier de connexion Claude sur cette machine et interroge le point de terminaison d'utilisation d'Anthropic, le même appel que celui effectué par /usage de Claude Code ; aucun élément de la connexion n'est stocké ou transmis ailleurs. Collie n'interroge le service que lorsqu'un panneau de ce harness est ouvert, et ignore tout fichier de connexion lisible par d'autres (toute permission plus permissive que 0600) ainsi que les connexions expirées. Codex n'envoie aucun jeton : il lit ses propres fichiers.

Un identifiant inconnu de Collie est ignoré avec un avertissement, et seuls les identifiants connus sont activés, de sorte qu'une faute de frappe n'active jamais une source non spécifiée. Dans le fichier de configuration, [bridge] account_windows accepte true ou false, une chaîne avec les mêmes formes, ou un tableau tel que ["claude", "codex"].

Chaque source lit des éléments différents.

• —
  Claude, activé par défaut. Collie lit ~/.claude/.credentials.json, ou $CLAUDE_CONFIG_DIR/.credentials.json, et interroge api.anthropic.com.
• —
  Codex, activé par défaut. Collie ne lit aucun identifiant de connexion et n'interroge aucun service. Lors d'une connexion ChatGPT, Codex écrit les fenêtres dans ses propres fichiers de session ($CODEX_HOME/sessions, ou ~/.codex/sessions), et Collie lit la fin des fichiers les plus récents des deux dernières heures. Un Codex utilisant une clé d'API n'a aucune fenêtre à afficher.
• —
  OpenCode Go, désactivé par défaut. Lorsque vous l'activez, Collie lit l'entrée opencode-go du magasin d'identifiants d'OpenCode (~/.local/share/opencode/auth.json, ou sous $XDG_DATA_HOME) et interroge opencode.ai. Sans entrée Go, il n'envoie aucune requête.
• —
  Grok, désactivé par défaut. Lorsque vous l'activez, Collie lit la connexion conservée par grok login (~/.grok/auth.json, ou sous $GROK_HOME) et interroge cli-chat-proxy.grok.com pour obtenir vos crédits.

Remarque. OpenCode Go et Grok suivent le format utilisé par d'autres outils pour ces endpoints, et aucun compte actif ne les a encore vérifiés. C'est pourquoi ils restent désactivés tant que vous ne les nommez pas. pi et OMP n'affichent aucune fenêtre ici pour l'instant.

collie doctor affiche chaque source dans sa ligne account-windows : activée ou désactivée, le fichier qu'elle lit et l'hôte qu'elle interroge. Terminaux contient le chemin statusLine.

Le point de contexte ne nécessite aucun réglage. Pour pi, OMP, Codex et OpenCode, Collie lit les jetons du dernier tour dans le journal de session. Il lit la fenêtre du modèle dans le journal de Codex, ou dans la propre liste de modèles du harness sur le disque (models-store.json de pi, models.db de OMP, ~/.cache/opencode/models.json d'OpenCode). Un modèle non mentionné dans cette liste ne reçoit aucun point de contexte ; le nom du modèle s'affiche tout de même. L'étiquette indique également le coût de la session en dollars après les points quand le harness en signale un : Claude Code via la ligne d'état encapsulée, pi, OMP et OpenCode à partir de leurs journaux. Codex n'en a aucun, son étiquette n'affiche donc aucun coût.

Mode sombre / mode clair

Remarque. Collie s'aligne par défaut sur l'apparence de votre téléphone.

Pour le figer, ouvrez Paramètres → Apparence, trouvez la carte Apparence sous la carte Thème, et choisissez Système, Clair ou Sombre. La carte Thème choisit les couleurs ; cette carte choisit leur déclinaison claire ou sombre. Le réglage est stocké par appareil dans le navigateur plutôt que sur le bridge. Votre téléphone peut rester en sombre pendant qu'un ordinateur portable suit l'OS. La préférence persiste après les rechargements et les réinstallations de la PWA sur le même appareil.

Le miroir du terminal est délibérément différent

Le miroir s'affiche toujours sur un fond sombre. Le mode clair inverse l'élément entier au lieu de recolorer les balises individuelles.

Les agents émettent des codes de couleur 24 bits absolus (38;2;r;g;b) conçus pour des fonds sombres, que les analyseurs en aval ne peuvent pas réassigner de manière fiable. Rendu directement sur du blanc, la plupart des sorties d'agents tombent sous un rapport de contraste de 3:1. L'inversion préserve le contraste prévu. Les mesures sont documentées dans l'ADR 0002.

Cette implémentation a deux conséquences pratiques :

• —
  Laissez vos agents configurés avec des thèmes sombres. Il s'agit de la configuration par défaut pour Claude Code, codex, opencode et pi. Si un agent utilise un thème clair, il émet des valeurs sombre sur clair qui deviennent illisibles dans Collie sous les deux modes. Cela provient de la sortie de l'agent et non de Collie lui-même.
• —
  Les diffs et les lignes surlignées s'affichent sous forme de blocs sombres en mode clair. Le contraste reste intact, mais le poids visuel est inversé.

Remarque. Installé sur iOS, en mode clair, le texte de la barre d'état reste blanc et peut se fondre dans l'arrière-plan. iOS ne permet pas aux applications web de modifier cette valeur de manière dynamique. Exécutez Collie directement dans le navigateur plutôt que sous forme de PWA installée pour contourner cette limitation.

Mode Zen

Remarque. Le mode Zen est désactivé par défaut.

Activez-le dans Paramètres → Appareil → Mode Zen (enregistré par appareil dans le navigateur). Cela ajoute une option Mode Zen au menu du panneau, sous le ⋮ à côté de Rechercher et Historique. Cliquez dessus pour masquer tous les éléments d'interface de Collie : l'en-tête, les bandeaux d'onglets et de panneaux, la ligne d'état de l'agent et les docks du compositeur. Seul le miroir du terminal reste visible. Un bouton flottant dans le coin supérieur droit ou la touche Échap restaure l'interface.

Le mode Zen est temporaire. La configuration persiste, mais l'état actif est réinitialisé lorsque vous changez de panneau ou rechargez la page. Les panneaux s'ouvrent toujours avec l'habillage standard.

Le miroir du terminal continue les requêtes périodiques en mode Zen, et les éléments interactifs du tampon restent fonctionnels. Les boutons de prompt ainsi que les commandes "Charger les éléments plus anciens" et "Afficher tout l'historique" restent disponibles car ils font partie du flux de contenu plutôt que de l'habillage.

Grands écrans

Remarque. Sur une tablette ou un Fold ouvert, l'écran des volets affiche plusieurs volets côte à côte. Un téléphone tenu verticalement et à plat ne change pas.

La disposition s'active pour l'écran des volets lorsque l'écran mesure au moins 600 pixels CSS de large et au moins 480 pixels de haut. Un téléphone tenu à l'horizontale fait moins de 480 pixels de haut, il conserve donc la disposition pour téléphone. Pour la désactiver, ouvrez Paramètres → Apparence → Disposition grand écran et choisissez Désactivé. Auto, la valeur par défaut, l'active lorsque l'écran est assez grand. Le choix est stocké par appareil.

La disposition comporte trois parties.

• —
  La barre latérale. Elle liste vos volets, la même liste que celle affichée par le sélecteur de volets. Le bouton dans sa rangée supérieure la réduit à un rail étroit d'icônes, et le choix est conservé sur cet appareil. La marque ColliePWA dans la rangée supérieure ramène à l'accueil. Nouvel espace et Paramètres se trouvent à son pied.
• —
  La rangée de volets. Chaque espace conserve sa propre rangée, et la rangée défile horizontalement. Appuyez sur un volet dans la barre latérale pour l'afficher. Maintenez-le enfoncé (clic droit à la souris) pour Ouvrir ici, qui remplace le volet où vous vous trouvez, ou Ouvrir à côté, qui l'ajoute à côté de ce volet. Vous pouvez également glisser un volet dans la rangée. Retirer de la vue retire un volet de la rangée. L'agent continue de tourner.
• —
  L'en-tête de l'espace. Il contient le nom de l'espace, ses onglets et un + pour un nouvel onglet. Maintenez un onglet enfoncé (clic droit à la souris) pour le Renommer ou le Fermer l'onglet, comme sur téléphone. Fermer l'onglet dans lequel vous travaillez vous déplace vers un volet de l'onglet adjacent. Ses deux boutons, ou un balayage vertical, permettent d'aller à l'espace au-dessus ou en dessous.

Chaque volet a une largeur : 1/2, 4/5 ou Plein de la rangée. Un volet n'est jamais plus étroit que 360 pixels, donc une largeur qui le rendrait plus étroit n'est pas proposée. Lorsque la rangée ne peut pas contenir deux volets à cette taille, chaque volet est en largeur Plein et la commande est masquée. La rangée s'aligne sur le début d'un volet lorsque vous arrêtez de défiler, et un défilement latéral ne revient jamais en arrière d'une page dans le navigateur. La rangée se termine toujours par Ajouter un volet. Il liste les volets de cet espace que la rangée n'affiche pas, chacun avec Ouvrir ici (le volet devient le dernier de la rangée). Il propose aussi Nouvel agent dans cet espace, qui ouvre la page Nouveau sur la machine et le dossier de ce volet et ajoute l'agent comme nouvel onglet de cet espace, à côté du volet où vous vous trouvez, ainsi que Nouvel agent dans un nouvel espace.

Chaque volet possède sa propre barre d'outils, sauf lorsque vous tenez un appareil pliable comme un ordinateur portable (voir ci-dessous). Le volet dans lequel vous travaillez possède un cadre et la boîte de réponse. Un appui sur la barre d'outils d'un autre volet agit sur ce volet et vous y déplace. Appuyez sur le volet pour vous déplacer sans agir.

La disposition est conservée sur cet appareil uniquement, et le retour arrière ainsi que les liens partagés fonctionnent comme avant.

Pliables. Sur un appareil pliable tenu semi-ouvert, Chrome et Samsung Internet divisent l'écran au niveau du pli. Tenu comme un ordinateur portable, la conversation reste au-dessus du pli, et la barre d'outils ainsi qu'une boîte de réponse plus haute se placent en dessous. Seul le volet dans lequel vous travaillez conserve sa barre d'outils, sous le pli. Les autres volets affichent uniquement le Chat. Cette division s'applique à n'importe quelle largeur, elle modifie donc également un téléphone à clapet semi-ouvert. La disposition redevient plate lorsque le clavier est ouvert. Tenu comme un livre, la division s'applique à partir de 600 pixels de large. Avec deux volets, chaque moitié affiche un volet et la barre latérale devient le rail. Avec un seul volet, la barre latérale reste ouverte dans une moitié et le volet remplit l'autre. Les autres navigateurs affichent uniquement la disposition plate.

Navigation entre les panneaux

Un geste vous déplace entre les panneaux et les espaces, sur téléphone comme sur grand écran. La gauche et la droite mènent au panneau précédent et suivant de l'espace, dans l'ordre du sélecteur. Le haut et le bas mènent à l'espace précédent et suivant. Au premier ou au dernier panneau ou espace, le déplacement reste sur place. Choisissez la méthode dans Paramètres → Apparence → Navigation entre les panneaux. Une modification s'applique à la prochaine ouverture d'un panneau.

L'encadré indique le panneau de destination, son statut, son espace et sa position dans l'espace, au-dessus d'un plan des espaces. Vous restez sur place si vous levez le premier doigt sans balayer, si vous le levez alors que le second doigt est encore posé, ou si vous posez un troisième doigt. Aucun élément sous vos doigts n'est activé quand ils se lèvent. La première fois que le geste est initié sur un appareil, un court message au-dessus de la barre explique son fonctionnement et indique où le désactiver.

Le geste conserve les interactions tactiles propres à la page. Un seul doigt maintenu ne fait rien de nouveau : un appui long sélectionne toujours du texte et ouvre son menu. Le pincement zoome toujours, car un second doigt posé dans les 300 premières ms compte comme un pincement. Un doigt en cours de défilement, ou débutant sur le bord gauche ou droit de l'écran où se trouve le geste de retour du téléphone, ne déclenche jamais le geste. À partir du moment où le second doigt se pose et jusqu'au lever du premier, la page bloque la sélection et le défilement, et toute sélection préalable est effacée. La navigation entre les panneaux est tactile uniquement ; la souris ne fait rien ici. Avec TalkBack activé, le geste ne fait rien car TalkBack s'approprie les balayages à deux doigts ; le sélecteur de panneaux fonctionne toujours.

Vue Chat

Remarque. Chat est la vue par défaut d'un panneau d'agent depuis la version 1.17.0. Le terminal est accessible en un geste.

Un panneau d'agent s'ouvre dans Chat. Chat affiche la conversation propre à l'agent au lieu du terminal : vos interventions, ses réponses, le raisonnement replié et une carte par étape. Le compositeur, la ceinture et le menu du panneau restent à leur place. Pour lire plutôt le terminal, ouvrez le menu ⋮ du panneau et appuyez sur Vue terminal. Ce choix s'applique à l'ensemble de l'appareil, est stocké dans le navigateur, et un appareil ayant déjà sélectionné le terminal le conserve. Vue Chat dans ce même menu permet de revenir en arrière.

Lorsque vous mettez un message en file d'attente pendant que Claude Code travaille, Chat l'affiche sur une carte En attente d'envoi, et le bouton Envoyer maintenant de la carte transmet immédiatement toute la file au tour en cours. Seul Claude Code propose cela, car le bouton déclenche Ctrl+Entrée, le raccourci que cet agent associe à cette action. Le bouton est masqué sur un appareil en lecture seule et sur une copie enregistrée.

La plupart des autres agents, dont OMP et pi, n'écrivent rien sur un message en file d'attente dans leur journal avant la fin du tour. Pour eux, Chat affiche les messages mis en file d'attente par Collie lui-même sur la même carte En attente d'envoi, jusqu'à ce que le journal de l'agent affiche chacun comme une invite. Cette carte n'a pas de bouton. Collie ne peut pas retirer un message de la file d'attente de l'agent, il n'y a donc pas d'annulation : pour le récupérer, arrêtez le tour.

Quand Collie ne peut plus déterminer où est passé un message en file d'attente, la carte affiche Non confirmé au lieu de disparaître. Cela se produit lorsque l'agent reste inactif avec une zone vide deux fois de suite, ou après 30 minutes sans tour en cours. Son bouton Abandonner retire la carte et n'envoie rien.

La roue crantée d'affichage propose une option Réponses stretchtext, désactivée par défaut. Une fois activée, le Chat, la carte de réponse complète et l'Historique affichent une réponse rédigée avec le plugin cc-stretch sous sa forme courte, et appuyer sur une expression la développe. Une {{name}} sans barre s'affiche comme name.

Un point précis dans Chat est connu comme incomplet. Hermes peut retirer un tour de son journal après sa lecture par Collie, par exemple lors d'un compactage. Chat continue alors d'afficher ce tour jusqu'à la prochaine relecture de la session. Le terminal ne rencontre jamais ce problème.

Chat lit le journal de session de l'agent, pas l'écran. Cela signifie qu'un panneau ne dispose de Chat que lorsque Collie sait quelle session s'exécute dans le panneau, et l'agent doit l'indiquer au multiplexeur. Le panneau ne peut pas le déduire lui-même.

OpenClaw ne nécessite aucune intégration Herdr pour Chat. Herdr ne transmet pas de session OpenClaw ; Collie lit donc le nom de session dans le pied de page de openclaw tui (agent main (main) | session work | …) et ouvre la base de données de session de cet agent sous $OPENCLAW_STATE_DIR, ou ~/.openclaw, en lecture seule. Définissez openclaw_root lorsque le dossier d'état est ailleurs. Le panneau doit se signaler à Herdr en tant qu'agent openclaw. Collie ne lit jamais le fichier de configuration d'OpenClaw ni son token de passerelle.

Kiro ne nécessite pas non plus d'intégration Herdr : Herdr nomme un panneau kiro-cli agent kiro, et Collie retrouve la session du panneau grâce au verrou qu'y maintient le processus Kiro actif. Collie lit les sessions Kiro V3, démarrées avec --v3 ou --agent-engine v3, ou avec V3 défini comme moteur dans les réglages de Kiro. Une session V1 ou V2 n'a ni Chat ni Historique. Définissez kiro_root lorsque Kiro stocke ses sessions ailleurs.

herdr integration status indique les intégrations installées. Un hook est lu au démarrage de l'agent ; un agent déjà en cours d'exécution lors de l'installation doit donc être redémarré. Oh My Pi correspond à l'intégration omp, pas à l'intégration pi : ce sont deux agents avec deux hooks, qui partagent un même format de journal.

Un nouveau panneau d'agent affiche Chat immédiatement, avant d'avoir le moindre contenu à lire, avec une seule ligne : « Send a message to start ». Codex ne signale sa session qu'après votre premier message, et pi n'écrit son journal qu'après sa première réponse ; les deux démarrent donc ainsi. La conversation s'affiche dès qu'elle existe.

Un panneau bascule sur le terminal lorsqu'un événement que Chat ne peut pas afficher survient : l'agent vous pose une question avant qu'il n'y ait quoi que ce soit à lire, ou son premier tour se termine alors qu'il n'a toujours ni session, ni fichier journal à lire. Le terminal affiche alors une ligne précisant ce qui manque, et la ligne ⋮ indique la cause. Un premier tour qui s'exécute pendant une minute sans rien à lire et sans autre signal bascule également. Un panneau déjà actif lors de sa première ouverture, sans session, affiche immédiatement le terminal. Lorsque la session ou le journal devient disponible ultérieurement, le panneau repasse dans Chat. Chat ne masque jamais cette ligne, ce qui permet de distinguer un hook manquant d'une fonctionnalité absente. collie doctor liste ces panneaux sous agent-sessions et mentionne la ligne d'intégration (integration-<agent>) qui résout chaque cas. Le page de dépannage détaille les étapes sous un panneau n'a ni Chat ni Historique.

Lecture hors ligne

Lorsque le bridge est inaccessible, le téléphone affiche la dernière copie enregistrée : vous pouvez la consulter sans pouvoir intervenir dessus.

Le téléphone conserve deux éléments pour chaque panneau : le dernier texte du terminal qu'il a reçu, et les tours Chat les plus récents tels que Chat les a restitués. Il ne conserve jamais l'écran brut du terminal sous forme de Chat. Lorsque vous ouvrez Collie et que le bridge ne répond pas au bout d'environ une seconde et demie, le téléphone affiche aussitôt cette copie enregistrée, puis la remplace par les données en direct dès que le bridge répond.

Une copie enregistrée se distingue d'un écran en direct :

• —
  La liste des agents est grisée, chaque état est au passé (« travaillait », « attendait votre action »), et l'en-tête indique à compter de ainsi que l'heure de sauvegarde.
• —
  Un panneau Chat affiche « Copie enregistrée le » suivi de l'heure. Le bridge conserve toujours les tours antérieurs.
• —
  Les boutons de prompt, les cartes et le bouton d'envoi sont désactivés. Un appui sur une copie enregistrée ne peut pas joindre l'agent.

La barre de connexion indique l'une des trois causes :

Un VPN tel que Tailscale maintient l'indicateur réseau du téléphone actif en mode avion, de sorte que la barre ne peut pas toujours distinguer « aucun réseau » de « le bridge est indisponible ». Elle indique alors seulement que le bridge ne répond pas.

Lorsque l'application est ouverte, la barre et la copie enregistrée apparaissent dès la première interrogation sans réponse. Une interrogation attend au maximum 6 secondes, soit une seconde de plus que le délai d'attente du bridge pour le multiplexeur. Une erreur serveur (5xx) est prise en compte à la deuxième occurrence consécutive. Ce qui est affiché reste à l'écran, et la première réponse active rétablit la vue en direct.

Juste après votre retour dans l'application, la première interrogation sans réponse ne compte pas à elle seule. Une connexion Tailscale peut nécessiter un instant pour se rétablir ; le téléphone effectue donc une nouvelle requête une demi-seconde plus tard et n'affiche la barre que si cette requête reste également sans réponse.

Conserver le chat sur ce téléphone, dans Paramètres → Appareil, définit la durée de conservation des échanges du Chat sur le téléphone :

Le texte du terminal a sa propre durée de vie de 24 heures, que ce paramètre ne modifie pas. Dans la vue du terminal, la seule copie hors ligne est ce texte de terminal.

Remarque. Le téléphone ne conserve que le texte déjà masqué par le bridge, et supprime la copie d'un panneau lorsque celui-ci demande un mot de passe. Ce que le téléphone conserve détaille chaque élément, sa limite de taille et sa durée de vie.

Modifications

Le Écran Fichiers affiche les modifications apportées par un agent aux dépôts git de son espace de travail, sous son segment Modifications. Deux paramètres propres à l'appareil déterminent la profondeur de recherche des dépôts, dans Paramètres → Appareil → Modifications :

Consultez Quel dossier, et quels dépôts pour savoir comment fonctionne la recherche.

Langue

L'interface de Collie est disponible en douze langues. Configurez ce choix sous Paramètres → Apparence → Langue.

• —
  English
• —
  Deutsch
• —
  Español
• —
  한국어
• —
  日本語
• —
  中文
• —
  Русский
• —
  Italiano
• —
  Français
• —
  Português
• —
  Türkçe

La sélection est enregistrée localement dans le navigateur par appareil. Le miroir du terminal n'est pas traduit : il affiche la sortie brute de l'agent, tandis que les réponses rapides, les libellés de menus et les touches correspondent aux noms de l'écran ou du clavier sous-jacents.

Le titre d'une notification suit le même choix : « claude needs you » arrive sous la forme « claude 입력 대기 » sur un appareil configuré en coréen. L'appareil applique le nouveau choix à la prochaine ouverture de Collie, et conserve ses titres dans la langue précédente jusque-là. Le corps du texte sous le titre correspond au nom et à l'emplacement propres au volet, et n'est jamais traduit (Web Push).