# Riferimento rapido Herdr

*Workspace, pane, stati degli agent, automazione CLI (v0.9.x)*

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

## Modello mentale

### Livelli

| Command | Description |
|---------|-------------|
| `session` | Namespace del server in background; possiede ogni processo |
| `workspace` | Uno per repo o task; la sidebar aggrega lo stato degli agent |
| `tab` | Un layout dentro un workspace (agent, log, server) |
| `pane` | Terminale reale; split a destra o in basso, sopravvive al detach |
| `agent` | Un coding agent che Herdr riconosce in un pane |

*Il detach del client lascia attivi il server e tutti i pane*

### Stati degli agent

| Command | Description |
|---------|-------------|
| `working` | L'agent è occupato in un turno |
| `blocked` | In attesa di un'approvazione o di una risposta |
| `done` | Finito, ma non l'hai ancora guardato |
| `idle` | Finito o in attesa, già visto |
| `unknown` | Agent presente, stato incerto; non prova che abbia finito |

*idle e done indicano entrambi che l'agent accetta un nuovo prompt*

### Modalità di input

| Command | Description |
|---------|-------------|
| `terminal` | I tasti vanno direttamente al pane attivo |
| `prefix` | Dopo Ctrl-b, il tasto successivo è un'azione Herdr |
| `navigate` | Navigazione persistente tra workspace |
| `copy` | Scrollback, ricerca e selezione da tastiera (Prefix [) |

## Per iniziare

### Installazione e avvio

```
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
```

### Integrazioni degli agent

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

*Le integrazioni riportano lo stato esatto e fanno riprendere gli agent dopo un riavvio del server*

### Prima il mouse

> Tutto è cliccabile: pane, tab, workspace, righe degli agent. Trascina i bordi per ridimensionare, clic destro per i menu di split e tab, trascina per selezionare e copiare. I tasti sono un livello opzionale in più.

## Scorciatoie da tastiera

### Da imparare per prime

| Command | Description |
|---------|-------------|
| `Prefix ?` | Mostra tutte le scorciatoie attive (/ per filtrare) |
| `Prefix c` | Nuova tab |
| `Prefix v` | Split: nuovo pane a destra |
| `Prefix -` | Split: nuovo pane sotto |
| `Prefix h/j/k/l` | Focus sul pane sx / giù / su / dx |
| `Prefix w` | Navigazione tra workspace |
| `Prefix q` | Detach; tutto resta in esecuzione |

*Il prefix predefinito è Ctrl-b. Il detach è q, non la d di tmux*

### Pane

| Command | Description |
|---------|-------------|
| `Prefix z` | Zoom (schermo intero) del pane attivo |
| `Prefix x` | Chiudi il pane |
| `Prefix Shift-h/j/k/l` | Scambia il pane col vicino |
| `Prefix r` | Modalità ridimensionamento |
| `Prefix Tab` | Passa al pane successivo |
| `Prefix Shift-p` | Rinomina il pane |
| `Prefix e` | Apri lo scrollback in un editor |

### Tab e workspace

| Command | Description |
|---------|-------------|
| `Prefix n / p` | Tab successiva / precedente |
| `Prefix 1..9` | Vai alla tab per numero |
| `Prefix Shift-t / Shift-x` | Rinomina / chiudi la tab |
| `Prefix Shift-n` | Nuovo workspace |
| `Prefix Shift-g` | Nuovo workspace su un git worktree |
| `Prefix Shift-w / Shift-d` | Rinomina / chiudi il workspace |
| `Prefix g` | Selettore Goto: ogni agent e terminale |
| `Prefix o` | Vai al pane dell'ultima notifica |
| `Prefix b` | Mostra/nascondi la sidebar |
| `Prefix s` | Impostazioni |

*Nel selettore Goto, b/w/i/d filtrano blocked/working/idle/done; / cerca*

### Modalità copia (Prefix [)

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | Sposta per carattere o parola |
| `Ctrl-u / Ctrl-d` | Mezza pagina su / giù |
| `/  ?  n  N` | Cerca avanti / indietro, ripeti |
| `v or Space` | Inizia la selezione |
| `y or Enter` | Copia la selezione ed esci |
| `q or Esc` | Esci senza copiare |

*Il pane resta in esecuzione mentre scorri indietro*

## Session e remoto

### Persistenza

```
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
```

### Workspace come worktree

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

## Scripting dei pane

### ID e contesto

> Gli ID hanno la forma w1 (workspace), w1:t1 (tab), w1:p1 (pane). In un pane Herdr sono impostati HERDR_ENV=1 e HERDR_PANE_ID. I comandi restituiscono JSON: leggi i nuovi ID dalla risposta, non dedurli mai dall'ordine della sidebar.

### Esplorare

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

### Eseguire un comando accanto

```
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
```

### Comandi dei pane

| Command | Description |
|---------|-------------|
| `pane run ID CMD` | Digita un comando e premi Invio in un passo |
| `pane send-text ID TEXT` | Digita testo letterale, senza Invio |
| `pane send-keys ID ctrl+c` | Invia tasti per nome |
| `pane wait-output --regex RE` | Blocca finché l'output corrisponde (regex Rust) |
| `pane zoom ID --toggle` | Zoom di un pane da script |
| `pane move ID --new-tab` | Sposta un pane; riceve un nuovo ID |
| `notification show TITLE` | Mostra un toast, anche con --sound done |

## Orchestrare gli agent

### Avvia, invia prompt, raccogli

```
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
```

### Comandi degli agent

| Command | Description |
|---------|-------------|
| `agent list` | Ogni agent attivo con il suo stato |
| `agent get NAME` | Pane, tipo e stato di un agent |
| `agent focus NAME` | Porta la UI su quell'agent (lo segna come visto) |
| `agent attach NAME` | Apri solo quel terminale, senza UI Herdr |
| `agent explain NAME` | Perché è stato rilevato questo stato |

*Il target è un nome di agent univoco o l'ID del pane che lo ospita*

### Comandi pane vs agent

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | Shell, test, server | Non vede lo stato degli agent |
| `agent` | Un coding agent rilevato | Rifiuta gli agent blocked |

### Regole pratiche

> agent start richiede un pane esistente fermo al prompt della shell; non crea mai layout. Usa --no-focus per il lavoro in background. Dopo un timeout, leggi l'agent prima di reinviare: il prompt potrebbe essere già arrivato.

## Configurazione

### ~/.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
```

### Comando popup personalizzato

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

### Comandi di configurazione

| Command | Description |
|---------|-------------|
| `herdr --default-config` | Stampa ogni opzione con commenti |
| `herdr config check` | Valida config.toml |
| `Prefix Shift-r` | Ricarica la config nel server attivo |
| `herdr config reset-keys` | Backup della config, via i binding custom |

*Gli accordi ctrl+alt sono le scorciatoie senza prefix più sicure tra terminali*