herdr : orchestrer ses agents dans le terminal

Ce guide est écrit depuis un pane herdr : la session qui le rédige tourne dans le serveur, HERDR_ENV=1, comme la plupart de mes sessions d’agents. Testé en v0.8.0. Je ne vais pas recopier la doc, elle est bien faite et à jour ; je vais dire ce que je fais avec au quotidien, ce que ça a changé, et les pièges dans lesquels je suis tombé.

Pourquoi j’ai arrêté de scroller mes panes tmux

Avec plusieurs sessions de coding agents en parallèle, le problème n’est plus d’ouvrir des terminaux, c’est de savoir qui attend, qui tourne, qui a fini depuis dix minutes. Un pane tmux est un rectangle opaque : rien ne dit ce que fait le process dedans, on scrolle, on devine.

Avant herdr, j’ai essayé d’apprendre l’état des agents à tmux : un hook poussait ● dans la status bar quand un tour tournait, une cloche quand l’agent attendait mon feu vert, ✓ quand il avait fini. Ça marchait à moitié : ça ne couvre qu’un agent, ça se rebranche outil par outil, et ça ne pilote rien. Le bricolage m’a confirmé le besoin, il ne l’a pas résolu.

herdr change la couche d’abstraction : chaque pane expose un état sémantique (idle, working, blocked, done), détecté depuis le contenu réel du terminal. Quand un agent s’arrête et a besoin d’une réponse, c’est marqué, on ne cherche plus le pane coincé un par un.

Ce que herdr est, en une phrase, et ce que ça change

herdr est un serveur de fond écrit en Rust (un binaire, pas d’Electron), Apache 2.0, soutenu par Y Combinator. Les terminaux vivent dans le serveur, pas dans une fenêtre d’app. Deux conséquences qui changent la vie :

• Fermer le laptop ne tue rien. Les sessions continuent, je réattache le matin depuis n’importe quel terminal, y compris en SSH.
• L’agent pilote l’outil. La CLI et le socket sont la même surface que celle que pilote l’agent : il peut créer des panes, lancer d’autres agents, les attendre. J’y reviens plus bas, c’est le point qui m’a fait basculer.

Installation :

# macOS · Linux
curl -fsSL https://herdr.dev/install.sh | sh

# ou homebrew
brew install herdr

Puis on lance herdr (TUI), ctrl+b q détache, herdr réattache.

Comment je range mon espace

Quatre niveaux, avec des identifiants publics stables :

w1          workspace
w1:t1       tab
w1:p1       pane
term_...    terminal

Les IDs sont des chaînes opaques : on les lit dans les réponses JSON, on ne les reconstruit jamais depuis l’affichage. herdr injecte le contexte courant dans chaque pane géré (HERDR_WORKSPACE_ID, HERDR_TAB_ID, HERDR_PANE_ID), et --current cible le pane appelant, ce qui évite de viser le pane focalisé d’un autre client.

Mon organisation : un workspace par projet actif, un tab par contexte dans le projet, un agent par pane. Pour une issue isolée, j’utilise le workflow herd-issue : un workspace jetable par issue (worktree + agent dédié), piloté par messages, détruit proprement quand tout est poussé. Le workspace jetable, c’est la différence avec tmux : on n’hésite plus à ouvrir un contexte, parce qu’on sait qu’il disparaîtra.

Le geste qui revient toutes les heures : lancer un agent, attendre, lire

Le flux complet, d’un shell à un agent qui a fini :

# 1. split à droite sans voler le focus
herdr pane split --current --direction right --no-focus

# 2. nommer le pane et lancer l'agent (sa TUI interactive)
herdr pane rename w1:p2 "reviewer"
herdr pane run w1:p2 "omp"

# 3. attendre que l'agent soit prêt, puis soumettre la tâche
herdr agent wait w1:p2 --until idle --timeout 30000
herdr pane run w1:p2 "Review the current diff and report only actionable findings."

# 4. attendre la fin, puis lire le transcript
herdr agent wait w1:p2 --until done --timeout 120000
herdr pane read w1:p2 --source recent-unwrapped --lines 120

La différence avec tmux tient aux étapes 3 et 4 : on attend un état au lieu de tirer des keystrokes et d’espérer. done signifie « fini et résultat pas encore vu » ; idle « fini et résultat vu » ; blocked signifie que l’agent attend une réponse, c’est lui qu’on va voir. Le matin, c’est spectaculaire : le pane qui a fini pendant la nuit est en done, celui qui a besoin d’une décision est en blocked, les autres sont restés en working. Le tableau de bord raconte la nuit, on ne scrolle plus rien.

Orchestrer plusieurs agents, concrètement

Le point fondateur, celui que tmux ne peut pas faire : l’agent lui-même pilote le multiplexeur. Le skill herdr du harnais vérifie d’abord qu’on est dans un pane géré (HERDR_ENV=1), puis expose split, run, wait et read au modèle. Concrètement, quand une session a besoin d’un contexte parallèle (un serveur de dev, une review longue, un test qui traîne), elle ouvre un pane avec --no-focus, lance la commande, attend la sortie, lit le résultat. Mon focus, lui, ne bouge pas : le travail en fond se fait sans me voler l’écran.

Entre agents, le même principe : un agent peut lancer un pair et lui envoyer un message, en attendant qu’il soit réellement bloqué avant d’intervenir. C’est le moteur du workflow herd-issue : un agent travaille sur un worktree isolé, on le pilote par messages, il demande l’approbation avant de pousser, et le workspace est démonté quand tout est terminé.

Les pièges qui m’ont coûté du temps

Vérifiés en v0.7.3, à re-vérifier à chaque version :

• herdr server reload-config ne valide qu’à moitié : une action inconnue dans un binding est ignorée silencieusement, « applied » ne prouve rien. Toujours tester le binding après rechargement.
• Les touches symboliques sont des positions QWERTY : sur un clavier AZERTY, des bindings morts sans aucun message. Si un raccourci ne répond pas, c’est probablement ça.

Et les règles de bon sens : ne pas fermer un workspace qu’on n’a pas créé, ne jamais tuer le process principal, ne pas lancer herdr server stop depuis une session active sauf intention explicite.

Les pickers que j’ai construits par-dessus — sélecteurs TV flous pour workspaces, tabs et panes, avec preview live par pane — et le détail complet de ces pièges (symptôme, cause, correctif) sont publics : herdr/.

Ce que ça change au quotidien

• Le matin : réattache, et les états racontent la nuit. Qui a fini, qui attend une décision, qui tourne encore.
• La journée : le focus ne bouge plus. L’agent ouvre et ferme ses propres panes pour le travail en fond, je reste sur ma session.
• Une issue : un workspace jetable, un agent dédié, un teardown propre. On n’hésite plus à isoler.
• Le soir : je ferme le laptop, les sessions continuent. La contrainte « il faut que ça tourne pendant que je suis là » a disparu.

Et l’honnêteté : la couche est jeune, les formats de config et de docs bougent encore (des migrations existent, ce qui prouve que ça bouge), et l’écosystème de plugins est plus jeune que celui de tmux. Je ne m’appuie dessus que sur ce que j’ai testé.

Par où commencer ?

Trois gestes, sans tout réorganiser :

1. Installe et lance (curl -fsSL https://herdr.dev/install.sh | sh, puis herdr), tmux reste sur tes serveurs.
2. Lance ton agent habituel dans un pane (claude, codex, opencode, omp, peu importe) et détache-toi : ctrl+b q, reviens plus tard, la session est là.
3. Donne le pilotage à l’agent : un skill qui vérifie HERDR_ENV, split avec --no-focus, et attend un état au lieu de tirer des keystrokes.

À l’usage, le multiplexeur cesse d’être un simple conteneur de terminaux : c’est le poste de pilotage du troupeau. Et comme pour le reste du harnais, les principes d’un workflow agentique et la gestion du contexte multi-agents complètent le tableau.