Herdr - Gestionnaire de terminaux pour agents de codage

Herdr

Herdr organise les terminaux en espaces de travail, onglets et panneaux, reconnaît les agents de codage qui s'exécutent dans les panneaux et expose la session en cours via la CLI herdr.

Avant d'émettre une commande de contrôle, vérifiez que cet agent s'exécute dans un panneau géré par Herdr :

test "${HERDR_ENV:-}" = 1

Si la vérification échoue, dites que vous n'êtes pas dans Herdr et arrêtez-vous. N'inspectez pas et ne contrôlez pas la session Herdr focalisée depuis l'extérieur d'Herdr.

Lorsque la vérification réussit, le binaire herdr dans PATH communique avec la session en cours. Utilisez-le pour inspecter le travail voisin, créer une disposition de terminal, lancer des agents et des commandes, lire la sortie et attendre des changements d'état.

Apprendre la CLI actuelle

Le binaire installé fait autorité pour la syntaxe des commandes. Commencez par :

herdr --help

Ensuite, affichez le groupe de commandes concerné en exécutant le groupe sans sous-commande :

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session

N'exécutez pas herdr nu pour la découverte ; il lance ou attache le TUI. Ne sondez pas une commande imbriquée mutante en omettant les arguments. Des commandes comme herdr workspace create sont valides avec les valeurs par défaut et seront exécutées.

La plupart des commandes de contrôle renvoient du JSON. Lisez les identifiants et l'état à partir de ces réponses au lieu de les prédire.

Comprendre la disposition, les panneaux et les agents

Choisissez la primitive qui correspond à la tâche :

• La topologie espace de travail, onglet et panneau organise les emplacements du terminal.
• Les commandes de panneau contrôlent les terminaux bruts, les shells, les tests, les serveurs, l'entrée et la sortie.
• Les commandes d'agent contrôlent l'agent de codage reconnu occupant actuellement un panneau.

Un panneau existe même s'il ne contient pas d'agent. agent start nécessite un panneau shell disponible existant et ne crée, ne divise ni ne déplace jamais la disposition. Utilisez les commandes de panneau pour les processus ordinaires. Utilisez les commandes d'agent lorsque Herdr doit valider l'identité de l'agent ou interpréter les états du cycle de vie idle, working, blocked, done et unknown.

Les commandes d'agent acceptent soit un nom d'agent actif unique, soit l'ID du panneau qui héberge actuellement cet agent. Elles n'acceptent pas les ID de terminal ni les étiquettes de type d'agent nues. Les noms doivent correspondre à [a-z][a-z0-9_-]{0,31} et être uniques parmi les agents actifs. Un nom suit l'occupant actuel du panneau et est effacé lorsque cet agent se termine, est libéré ou est remplacé.

idle signifie que l'agent est prêt à recevoir une entrée et que son onglet a été vu dans l'interface Herdr focalisée. done est le même état idle sous-jacent après la fin d'un travail en arrière-plan non vu. Focaliser l'onglet ou cibler le panneau ou l'agent avec une commande de focus le marque comme vu. Les lectures CLI ne le marquent pas comme vu. blocked signifie qu'Herdr a reconnu une interface d'approbation ou de question. unknown signifie qu'un agent est présent mais qu'Herdr ne peut pas le classer avec certitude ; cela ne prouve pas l'achèvement.

Utiliser les ID et le contexte de l'appelant

Les ID publics sont des poignées stables opaques :

• workspace : w1
• tab : w1:t1
• pane : w1:p1

Les ID d'onglet et de panneau fermés ne sont pas réutilisés. Un panneau déplacé dans un autre espace de travail reçoit un nouvel ID de panneau qualifié par l'espace de travail. Après pane move, continuez avec .result.move_result.pane.pane_id ou le nom de l'agent actif. L'ancienne valeur est rapportée comme .result.move_result.previous_pane_id ; seul le contexte d'appel hérité du processus déplacé continue de résoudre cet ancien ID, ne l'utilisez donc pas comme cible générale d'agent.

Herdr injecte le contexte de l'appelant dans chaque panneau géré :

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

Préférez --current lorsqu'une commande de panneau doit cibler le panneau appelant. Omettre une cible peut utiliser le panneau focalisé par l'interface, qui peut appartenir à l'utilisateur ou à un autre client.

Découvrez l'état actif avec :

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

Les réponses de création exposent les ID à utiliser ensuite. workspace create renvoie .result.workspace, .result.tab et .result.root_pane. tab create renvoie .result.tab et .result.root_pane. pane split renvoie le nouveau panneau comme .result.pane.

Démarrer et coordonner un agent

Par défaut, utilisez un panneau frère dans l'onglet actuel et le répertoire de travail actuel. Ne créez pas d'espace de travail, d'onglet, d'arborescence de travail ou de répertoire de travail différent sauf si l'utilisateur le demande explicitement.

Respectez une direction demandée par l'utilisateur. Sinon, inspectez le panneau appelant :

herdr pane layout --pane "$HERDR_PANE_ID"

Divisez un panneau large vers la droite et un panneau étroit ou haut vers le bas. Évitez les divisions répétées dans la même direction qui créent des colonnes trop étroites ou des lignes trop courtes. Gardez le focus de l'utilisateur dans le panneau appelant et préservez explicitement le répertoire de travail de l'appelant :

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Remplacez right par down le cas échéant. Lisez le nouvel ID de panneau depuis .result.pane.pane_id.

Un panneau shell disponible doit être à son invite interactive, avec le shell lui-même au premier plan et aucune commande de premier plan, éditeur ou agent en cours. Démarrez un agent pris en charge dans ce panneau avec un nom unique utile :

herdr agent start reviewer --kind codex --pane <id-du-panneau-retourne>

Utilisez le type demandé par l'utilisateur. Exécutez herdr agent pour inspecter la liste des types installés et les options. Transmettez les arguments natifs de l'agent uniquement après -- :

herdr agent start reviewer --kind codex --pane <id-du-panneau-retourne> -- <args-agent...>

agent start ne revient que lorsque Herdr détecte l'agent attendu dans le même panneau et le considère prêt pour une entrée interactive. Le délai d'attente par défaut est de 30 secondes.

Soumettez le travail via la surface de l'agent :

herdr agent prompt reviewer "Passez en revue le diff actuel et signalez uniquement les conclusions exploitables." --wait --timeout 120000

agent prompt soumet atomiquement le texte et la touche Entrée encodée tout en respectant le mode bracketed-paste actif du panneau. Pour un travail d'agent normal, --wait suffit : il attend le premier état stable idle, done ou blocked. Ne répétez pas ces valeurs par défaut avec --until.

Un prompt envoyé depuis un état non-travail doit produire un changement de cycle de vie observé dans les cinq secondes. Sinon, Herdr renvoie agent_prompt_stalled au lieu d'attendre indéfiniment. Cette attente suit l'état du cycle de vie, pas un tour individuel ; si l'agent travaille déjà, l'achèvement du tour actif peut le satisfaire.

Utilisez --until uniquement pour un workflow spécifique à un état, comme attendre qu'un agent en cours d'exécution demande une entrée :

herdr agent wait reviewer --until blocked --timeout 120000

Sans --until, agent wait autonome utilise les mêmes valeurs par défaut d'état stable que agent prompt --wait.

Utilisez des touches logiques pour les contrôles interactifs de l'interface agent :

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr valide toutes les touches avant d'écrire un seul octet. Lisez le résultat via l'agent résolu :

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

Si une attente échoue ou renvoie blocked, inspectez agent get et agent read avant de décider quoi envoyer. Utilisez la surface du panneau uniquement lorsque le contrôle brut du terminal est intentionnel.

Exécuter une commande ordinaire dans un autre panneau

Créez un panneau frère avec la même règle de géométrie, préservez le répertoire de travail de l'appelant et ne modifiez pas le focus de l'utilisateur :

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Lisez le nouvel ID de panneau depuis .result.pane.pane_id, puis exécutez et inspectez la commande :

herdr pane run <id-du-panneau-retourne> "just test"
herdr pane wait-output <id-du-panneau-retourne> --match "résultat du test" --timeout 120000
herdr pane read <id-du-panneau-retourne> --source recent-unwrapped --lines 120

pane run envoie atomiquement le texte de la commande et la touche Entrée. pane wait-output recherche la capture sélectionnée immédiatement, donc une sortie qui existe déjà peut correspondre. Utilisez --match <texte> pour une sous-chaîne littérale ou --regex <motif> pour une expression régulière Rust. Omettre --timeout permet une attente indéfinie.

Utilisez la source de lecture qui correspond à la tâche :

• visible : la zone d'affichage actuellement rendue.
• recent : la sortie rendue récente, y compris les retours à la ligne logiciels.
• recent-unwrapped : la sortie récente avec les retours à la ligne logiciels joins ; à privilégier pour les journaux et les transcriptions.
• detection : la capture instantanée en texte brut du tampon inférieur utilisée pour la détection des agents.

Utilisez --format ansi lorsque les couleurs et le style du terminal sont des preuves. Sinon, utilisez le texte.

--lines demande à Herdr plus de lignes à partir de l'écran disponible du panneau et du défilement arrière de l'hôte. Si l'augmenter ne révèle pas plus d'une réponse terminée, le panneau exécute probablement l'agent sur l'écran alternatif du terminal. Les lignes qui quittent l'écran alternatif n'entrent pas dans le défilement arrière de l'hôte d'Herdr, donc un nombre de lignes plus important ne peut pas les récupérer.

Après cette lecture échouée, demandez à l'agent d'écrire sa réponse complète en Markdown dans un répertoire temporaire et de répondre uniquement avec le chemin du fichier, puis lisez le fichier directement. Utilisez ceci uniquement comme solution de repli ; ne demandez pas de sortie de fichier dans le prompt initial.

Règles de sécurité et de coordination

• Utilisez --no-focus pour le travail en arrière-plan, sauf si l'utilisateur a demandé de changer de contexte.
• Utilisez --current, un ID de panneau explicite ou un nom d'agent unique. Ne vous fiez pas au panneau focalisé d'un autre client.
• Analysez les ID à partir des réponses JSON. Ne les déduisez pas de l'ordre de la barre latérale ou d'exemples.
• Ne fermez pas les espaces de travail, onglets, panneaux ou sessions que vous n'avez pas créés, sauf si l'utilisateur le demande explicitement.
• N'exécutez jamais herdr server stop depuis une session active, sauf si l'utilisateur a explicitement l'intention d'arrêter le serveur et ses processus de panneau.
• Ne tuez jamais le processus principal d'Herdr. Utilisez des sessions de test nommées pour les expériences nécessitant un serveur isolé.
• Les erreurs serveur CLI sont en JSON sur stderr avec le code de sortie 1. Les erreurs de syntaxe CLI se terminent avec le code de sortie 2.

Idiomes locaux

La condition HERDR_ENV=1 ci-dessus s'applique au contrôle de la session en cours depuis l'intérieur d'un panneau. Le travail au niveau de l'hôte — modification de la configuration, installation de plugins, débogage de la détection d'agents, construction d'automatisation autour du socket/CLI — est légitime depuis n'importe quel terminal. Pour ces tâches, lisez references/local-idioms.md : configuration de la livraison de notifications, maintenance de la détection d'agents, métadonnées de la barre latérale à partir des hooks Claude Code, modèles d'abonnement aux événements, workflow d'arborescence de travail et notes pour les auteurs de plugins.