# Referência Rápida do Herdr

*Workspaces, panes, estados de agent, automação via CLI (v0.9.x)*

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

## Modelo Mental

### Camadas

| Command | Description |
|---------|-------------|
| `session` | Namespace do servidor em segundo plano; dono dos processos |
| `workspace` | Um por repo ou tarefa; a sidebar resume o estado |
| `tab` | Um layout dentro do workspace (agents, logs, servidor) |
| `pane` | Terminal real; divide à direita/abaixo, sobrevive ao detach |
| `agent` | Agente de código que o Herdr reconhece num pane |

*Desanexar o cliente mantém o servidor e todos os panes rodando*

### Estados do Agent

| Command | Description |
|---------|-------------|
| `working` | Agent ocupado em um turno |
| `blocked` | Aguardando aprovação ou resposta a uma pergunta |
| `done` | Terminou, e você ainda não viu |
| `idle` | Terminou ou aguarda, já visto |
| `unknown` | Agent presente, estado incerto; não prova que terminou |

*idle e done significam que o agent aceita um novo prompt*

### Modos de Entrada

| Command | Description |
|---------|-------------|
| `terminal` | Teclas vão direto para o pane em foco |
| `prefix` | Após Ctrl-b, a próxima tecla é uma ação do Herdr |
| `navigate` | Superfície persistente de navegação de workspaces |
| `copy` | Scrollback, busca e seleção pelo teclado (Prefix [) |

## Primeiros Passos

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

### Integrações de Agents

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

*Integrações informam o estado exato e retomam agents após reiniciar o servidor*

### Mouse Primeiro

> Tudo é clicável: panes, tabs, workspaces, linhas de agent. Arraste bordas para redimensionar, clique direito para menus de split e tab, arraste para copiar. Teclas são uma camada opcional.

## Atalhos de Teclado

### Aprenda Estes Primeiro

| Command | Description |
|---------|-------------|
| `Prefix ?` | Mostrar todos os atalhos ativos (/ filtra) |
| `Prefix c` | Nova tab |
| `Prefix v` | Split: novo pane à direita |
| `Prefix -` | Split: novo pane abaixo |
| `Prefix h/j/k/l` | Focar pane esquerda / baixo / cima / direita |
| `Prefix w` | Navegação de workspaces |
| `Prefix q` | Detach; tudo continua rodando |

*O prefix padrão é Ctrl-b. Detach é q, não o d do tmux*

### Panes

| Command | Description |
|---------|-------------|
| `Prefix z` | Zoom (tela cheia) do pane em foco |
| `Prefix x` | Fechar pane |
| `Prefix Shift-h/j/k/l` | Trocar pane com o vizinho |
| `Prefix r` | Modo de redimensionar |
| `Prefix Tab` | Ir para o próximo pane |
| `Prefix Shift-p` | Renomear pane |
| `Prefix e` | Abrir scrollback em um editor |

### Tabs e Workspaces

| Command | Description |
|---------|-------------|
| `Prefix n / p` | Tab seguinte / anterior |
| `Prefix 1..9` | Ir para a tab pelo número |
| `Prefix Shift-t / Shift-x` | Renomear / fechar tab |
| `Prefix Shift-n` | Novo workspace |
| `Prefix Shift-g` | Novo workspace em um git worktree |
| `Prefix Shift-w / Shift-d` | Renomear / fechar workspace |
| `Prefix g` | Seletor Goto: todos os agents e terminais |
| `Prefix o` | Ir ao pane da última notificação |
| `Prefix b` | Alternar sidebar |
| `Prefix s` | Configurações |

*No seletor Goto, b/w/i/d filtram blocked/working/idle/done; / busca*

### Modo de Cópia (Prefix [)

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | Mover por caractere ou palavra |
| `Ctrl-u / Ctrl-d` | Meia página acima / abaixo |
| `/  ?  n  N` | Buscar adiante / atrás, repetir |
| `v or Space` | Iniciar seleção |
| `y or Enter` | Copiar seleção e sair |
| `q or Esc` | Sair sem copiar |

*O pane continua rodando enquanto você rola o histórico*

## Sessions e Acesso Remoto

### Persistência

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

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

## Scripts com Panes

### IDs e Contexto

> IDs têm a forma w1 (workspace), w1:t1 (tab), w1:p1 (pane). Dentro de um pane do Herdr, HERDR_ENV=1 e HERDR_PANE_ID são definidos. Comandos retornam JSON: leia os novos IDs da resposta, nunca os deduza pela ordem da sidebar.

### Descobrir

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

### Rodar um Comando ao 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` | Digitar um comando e pressionar Enter de uma vez |
| `pane send-text ID TEXT` | Digitar texto literal, sem Enter |
| `pane send-keys ID ctrl+c` | Enviar teclas nomeadas |
| `pane wait-output --regex RE` | Bloquear até a saída casar (regex Rust) |
| `pane zoom ID --toggle` | Dar zoom em um pane via script |
| `pane move ID --new-tab` | Mover um pane; ele recebe um novo ID |
| `notification show TITLE` | Exibir um toast, opcionalmente com --sound done |

## Orquestrando Agents

### Iniciar, Instruir, Coletar

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

| Command | Description |
|---------|-------------|
| `agent list` | Todos os agents ativos com seu estado |
| `agent get NAME` | Pane, tipo e estado de um agent |
| `agent focus NAME` | Levar a UI até o agent (marca como visto) |
| `agent attach NAME` | Abrir só aquele terminal, sem a UI do Herdr |
| `agent explain NAME` | Por que a detecção escolheu este estado |

*Alvos são um nome único de agent ou o ID do pane que o hospeda*

### Comandos pane vs agent

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | Shells, testes, servidores | Não vê o estado do agent |
| `agent` | Um agente de código detectado | Recusa agents em blocked |

### Regras Práticas

> agent start exige um pane existente parado no prompt do shell; ele nunca cria layout. Use --no-focus para trabalho em segundo plano. Após um timeout, leia o agent antes de reenviar: o prompt pode já ter chegado.

## Configuração

### ~/.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 Configuração

| Command | Description |
|---------|-------------|
| `herdr --default-config` | Imprimir todas as opções com comentários |
| `herdr config check` | Validar config.toml |
| `Prefix Shift-r` | Recarregar config no servidor em execução |
| `herdr config reset-keys` | Fazer backup da config, remover atalhos próprios |

*Combinações ctrl+alt são os atalhos sem prefix mais seguros entre terminais*