# Referencia Rápida de Herdr

*Workspaces, panes, estados de agente, automatización CLI (v0.9.x)*

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

## Modelo Mental

### Capas

| Command | Description |
|---------|-------------|
| `session` | Espacio del servidor en segundo plano; dueño de todo proceso |
| `workspace` | Uno por repo o tarea; la barra lateral resume estados |
| `tab` | Un layout dentro de un workspace (agentes, logs, servidor) |
| `pane` | Terminal real; se divide a derecha o abajo, sobrevive al detach |
| `agent` | Un agente de código que Herdr reconoce en un pane |

*Desconectar el cliente deja el servidor y todos los panes en ejecución*

### Estados del Agente

| Command | Description |
|---------|-------------|
| `working` | El agente está ocupado en un turno |
| `blocked` | Esperando una aprobación o una pregunta |
| `done` | Terminó y aún no lo has revisado |
| `idle` | Terminó o espera; ya revisado |
| `unknown` | Agente presente, estado incierto; no prueba que terminó |

*idle y done indican que el agente acepta un nuevo prompt*

### Modos de Entrada

| Command | Description |
|---------|-------------|
| `terminal` | Las teclas van directo al pane enfocado |
| `prefix` | Tras Ctrl-b, la siguiente tecla es una acción de Herdr |
| `navigate` | Navegación persistente entre workspaces |
| `copy` | Historial, búsqueda y selección con teclado (Prefix [) |

## Primeros Pasos

### Instalar e Iniciar

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

### Integraciones de Agentes

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

*Las integraciones reportan el estado exacto y reanudan agentes tras reiniciar el servidor*

### Primero el Ratón

> Todo es clicable: panes, tabs, workspaces, filas de agentes. Arrastra bordes para redimensionar, clic derecho para menús de split y tab, arrastra para copiar. Las teclas son opcionales.

## Atajos de Teclado

### Aprende Estos Primero

| Command | Description |
|---------|-------------|
| `Prefix ?` | Mostrar todos los atajos activos (/ para filtrar) |
| `Prefix c` | Nuevo tab |
| `Prefix v` | Dividir: nuevo pane a la derecha |
| `Prefix -` | Dividir: nuevo pane abajo |
| `Prefix h/j/k/l` | Enfocar pane izquierda / abajo / arriba / derecha |
| `Prefix w` | Navegación de workspaces |
| `Prefix q` | Detach; todo sigue en ejecución |

*El prefix predeterminado es Ctrl-b. Detach es q, no la d de tmux*

### Panes

| Command | Description |
|---------|-------------|
| `Prefix z` | Zoom (pantalla completa) del pane enfocado |
| `Prefix x` | Cerrar pane |
| `Prefix Shift-h/j/k/l` | Intercambiar pane con su vecino |
| `Prefix r` | Modo redimensionar |
| `Prefix Tab` | Ciclar al siguiente pane |
| `Prefix Shift-p` | Renombrar pane |
| `Prefix e` | Abrir el historial en un editor |

### Tabs y Workspaces

| Command | Description |
|---------|-------------|
| `Prefix n / p` | Tab siguiente / anterior |
| `Prefix 1..9` | Ir a un tab por número |
| `Prefix Shift-t / Shift-x` | Renombrar / cerrar tab |
| `Prefix Shift-n` | Nuevo workspace |
| `Prefix Shift-g` | Nuevo workspace en un git worktree |
| `Prefix Shift-w / Shift-d` | Renombrar / cerrar workspace |
| `Prefix g` | Selector Goto: todo agente y terminal |
| `Prefix o` | Ir al pane de la última notificación |
| `Prefix b` | Alternar barra lateral |
| `Prefix s` | Ajustes |

*En el selector Goto, b/w/i/d filtran blocked/working/idle/done; / busca*

### Modo Copia (Prefix [)

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | Mover por carácter o palabra |
| `Ctrl-u / Ctrl-d` | Media página arriba / abajo |
| `/  ?  n  N` | Buscar adelante / atrás, repetir |
| `v or Space` | Iniciar selección |
| `y or Enter` | Copiar selección y salir |
| `q or Esc` | Salir sin copiar |

*El pane sigue en ejecución mientras revisas el historial*

## Sessions y Remoto

### Persistencia

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

### Por 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 como Worktrees

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

## Scripting de Panes

### IDs y Contexto

> Los IDs son como w1 (workspace), w1:t1 (tab), w1:p1 (pane). Dentro de un pane de Herdr se definen HERDR_ENV=1 y HERDR_PANE_ID. Los comandos devuelven JSON: lee los IDs nuevos de la respuesta, nunca los deduzcas del orden de la barra lateral.

### Descubrir

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

### Ejecutar un Comando al Lado

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

### Comandos de Pane

| Command | Description |
|---------|-------------|
| `pane run ID CMD` | Escribir un comando y pulsar Enter en un paso |
| `pane send-text ID TEXT` | Escribir texto literal, sin Enter |
| `pane send-keys ID ctrl+c` | Enviar teclas por nombre |
| `pane wait-output --regex RE` | Bloquear hasta que la salida coincida (regex de Rust) |
| `pane zoom ID --toggle` | Zoom de un pane desde un script |
| `pane move ID --new-tab` | Mover un pane; recibe un ID nuevo |
| `notification show TITLE` | Mostrar un toast, opcionalmente con --sound done |

## Orquestar Agentes

### Iniciar, Instruir, Recoger

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

### Comandos de Agente

| Command | Description |
|---------|-------------|
| `agent list` | Todos los agentes activos con su estado |
| `agent get NAME` | Pane, tipo y estado de un agente |
| `agent focus NAME` | Llevar la UI a ese agente (lo marca visto) |
| `agent attach NAME` | Abrir solo esa terminal, sin la UI de Herdr |
| `agent explain NAME` | Por qué la detección eligió este estado |

*El destino es un nombre de agente único o el ID del pane que lo aloja*

### Comandos pane vs agent

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | Shells, tests, servidores | No ve el estado del agente |
| `agent` | Un agente de código detectado | Rechaza agentes blocked |

### Reglas Prácticas

> agent start necesita un pane existente en un prompt de shell; nunca crea layout. Usa --no-focus para trabajo en segundo plano. Tras un timeout, lee el agente antes de reenviar: el prompt quizá ya llegó.

## Configuración

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

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

### Comandos de Config

| Command | Description |
|---------|-------------|
| `herdr --default-config` | Imprimir todas las opciones con comentarios |
| `herdr config check` | Validar config.toml |
| `Prefix Shift-r` | Recargar config en el servidor activo |
| `herdr config reset-keys` | Respaldar config, quitar atajos personalizados |

*Los acordes ctrl+alt son los atajos sin prefix más seguros entre terminales*