# Référence rapide Herdr

*Workspaces, panes, états des agents, automatisation CLI (v0.9.x)*

> Source: Herdr documentation (herdr.dev, v0.9.3) and herdr CLI help output · MIT

## Modèle mental

### Couches

| Command | Description |
|---------|-------------|
| `session` | Espace de noms du serveur ; possède tous les processus |
| `workspace` | Un par dépôt/tâche ; la barre latérale agrège les états |
| `tab` | Une disposition dans un workspace (agents, logs, serveur) |
| `pane` | Vrai terminal ; division droite ou bas, survit au détachement |
| `agent` | Un agent de code reconnu par Herdr dans un pane |

*Détacher le client laisse tourner le serveur et tous les panes*

### États des agents

| Command | Description |
|---------|-------------|
| `working` | L'agent traite un tour |
| `blocked` | Attend une approbation ou une réponse |
| `done` | Terminé, pas encore consulté |
| `idle` | Terminé ou en attente, déjà consulté |
| `unknown` | Agent présent, état incertain ; pas une preuve de fin |

*idle et done signifient tous deux que l'agent accepte un nouveau prompt*

### Modes de saisie

| Command | Description |
|---------|-------------|
| `terminal` | Les touches vont directement au pane actif |
| `prefix` | Après Ctrl-b, la touche suivante est une action Herdr |
| `navigate` | Surface de navigation persistante entre workspaces |
| `copy` | Historique au clavier, recherche et sélection (Prefix [) |

## Premiers pas

### Installer et lancer

```
curl -fsSL https://herdr.dev/install.sh | sh
cd ~/projects/app
herdr           # launch or attach
claude          # any agent, auto-detected
herdr update    # self-update
herdr status    # client vs server version
```

### Intégrations d'agents

```
herdr integration install claude
herdr integration install codex
herdr integration status --outdated-only
```

*Les intégrations rapportent l'état exact et permettent de reprendre après un redémarrage du serveur*

### Souris d'abord

> Tout est cliquable : panes, tabs, workspaces, lignes d'agents. Glisser les bordures pour redimensionner, clic droit pour les menus de division et de tab, glisser-sélectionner pour copier. Les touches sont une couche optionnelle.

## Raccourcis clavier

### À apprendre d'abord

| Command | Description |
|---------|-------------|
| `Prefix ?` | Afficher tous les raccourcis actifs (/ pour filtrer) |
| `Prefix c` | Nouveau tab |
| `Prefix v` | Diviser : nouveau pane à droite |
| `Prefix -` | Diviser : nouveau pane en dessous |
| `Prefix h/j/k/l` | Focus pane gauche / bas / haut / droite |
| `Prefix w` | Navigation entre workspaces |
| `Prefix q` | Se détacher ; tout continue de tourner |

*Le prefix par défaut est Ctrl-b. Détacher : q, pas le d de tmux*

### Panes

| Command | Description |
|---------|-------------|
| `Prefix z` | Zoom (plein écran) du pane actif |
| `Prefix x` | Fermer le pane |
| `Prefix Shift-h/j/k/l` | Échanger le pane avec son voisin |
| `Prefix r` | Mode redimensionnement |
| `Prefix Tab` | Passer au pane suivant |
| `Prefix Shift-p` | Renommer le pane |
| `Prefix e` | Ouvrir l'historique dans un éditeur |

### Tabs et workspaces

| Command | Description |
|---------|-------------|
| `Prefix n / p` | Tab suivant / précédent |
| `Prefix 1..9` | Aller au tab par numéro |
| `Prefix Shift-t / Shift-x` | Renommer / fermer le tab |
| `Prefix Shift-n` | Nouveau workspace |
| `Prefix Shift-g` | Nouveau workspace sur un worktree git |
| `Prefix Shift-w / Shift-d` | Renommer / fermer le workspace |
| `Prefix g` | Sélecteur Goto : tous les agents et terminaux |
| `Prefix o` | Aller au pane de la dernière notification |
| `Prefix b` | Afficher/masquer la barre latérale |
| `Prefix s` | Paramètres |

*Dans Goto, b/w/i/d filtrent blocked/working/idle/done ; / recherche*

### Mode copie (Prefix [)

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | Déplacer par caractère ou par mot |
| `Ctrl-u / Ctrl-d` | Demi-page haut / bas |
| `/  ?  n  N` | Chercher en avant / arrière, répéter |
| `v or Space` | Commencer la sélection |
| `y or Enter` | Copier la sélection et quitter |
| `q or Esc` | Quitter sans copier |

*Le pane continue de tourner pendant que vous remontez l'historique*

## Sessions et accès distant

### Persistance

```
herdr                      # reattach
herdr session list
herdr session attach work  # isolated server
herdr session stop work
herdr server stop          # kills ALL panes
```

### Via SSH

```
herdr --remote workbox  # local UI, remote panes
herdr --remote workbox --session agents
herdr machine add workbox --label box
herdr --machine box agent list
```

### Workspaces comme worktrees

```
herdr worktree create --branch fix/login --base main
herdr worktree list
herdr worktree remove --workspace w3
```

## Scripter les panes

### IDs et contexte

> Les IDs ressemblent à w1 (workspace), w1:t1 (tab), w1:p1 (pane). Dans un pane Herdr, HERDR_ENV=1 et HERDR_PANE_ID sont définis. Les commandes renvoient du JSON : lire les nouveaux IDs dans la réponse, ne jamais les deviner d'après l'ordre de la barre latérale.

### Découvrir

```
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr pane layout --current
```

### Lancer une commande à côté

```
id=$(herdr pane split --current \
       --direction right --no-focus \
     | jq -r .result.pane.pane_id)
herdr pane run "$id" "npm test"
herdr pane wait-output "$id" \
  --match "passed" --timeout 120000
herdr pane read "$id" --lines 80 \
  --source recent-unwrapped
```

### Commandes de pane

| Command | Description |
|---------|-------------|
| `pane run ID CMD` | Taper une commande et valider en une étape |
| `pane send-text ID TEXT` | Taper du texte littéral, sans Entrée |
| `pane send-keys ID ctrl+c` | Envoyer des touches nommées |
| `pane wait-output --regex RE` | Bloquer jusqu'à correspondance (regex Rust) |
| `pane zoom ID --toggle` | Zoomer un pane depuis un script |
| `pane move ID --new-tab` | Déplacer un pane ; il reçoit un nouvel ID |
| `notification show TITLE` | Afficher un toast, avec --sound done en option |

## Orchestrer les agents

### Démarrer, solliciter, récupérer

```
herdr agent start reviewer --kind codex --pane "$id"
herdr agent prompt reviewer "Review the diff" \
  --wait --timeout 300000
herdr agent read reviewer --lines 120
herdr agent wait reviewer --until blocked
herdr agent send-keys reviewer esc
```

### Commandes d'agent

| Command | Description |
|---------|-------------|
| `agent list` | Tous les agents actifs avec leur état |
| `agent get NAME` | Pane, type et état d'un agent |
| `agent focus NAME` | Amener l'UI sur cet agent (le marque vu) |
| `agent attach NAME` | Ouvrir ce seul terminal, sans l'UI Herdr |
| `agent explain NAME` | Pourquoi la détection a choisi cet état |

*Cibles : un nom d'agent unique ou l'ID du pane qui l'héberge*

### Commandes pane vs agent

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | Shells, tests, serveurs | Ignore l'état des agents |
| `agent` | Un agent de code détecté | Refuse les agents blocked |

### Règles pratiques

> agent start exige un pane existant, posé sur une invite shell ; il ne crée jamais de disposition. Utiliser --no-focus en arrière-plan. Après un timeout, lire l'agent avant de renvoyer : le prompt est peut-être déjà arrivé.

## Configuration

### ~/.config/herdr/config.toml

```
[keys]
prefix = "ctrl+a"
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
[theme]
name = "tokyo-night"
[ui.toast]
delivery = "system"  # or herdr / terminal
```

### Commande popup personnalisée

```
[[keys.command]]
key = "prefix+alt+g"
type = "popup"       # or "pane" / "shell"
command = "lazygit"
width = "80%"
height = "80%"
```

### Commandes de config

| Command | Description |
|---------|-------------|
| `herdr --default-config` | Afficher toutes les options avec commentaires |
| `herdr config check` | Valider config.toml |
| `Prefix Shift-r` | Recharger la config dans le serveur actif |
| `herdr config reset-keys` | Sauvegarder la config, retirer les raccourcis perso |

*Les accords ctrl+alt sont les raccourcis sans prefix les plus sûrs entre terminaux*