Herdr (pt-BR)

Herdr

Herdr organiza terminais em workspaces, abas e painéis, reconhece agentes de codificação executando dentro dos painéis e expõe a sessão atual através da CLI herdr.

Antes de emitir qualquer comando de controle, verifique se este agente está executando dentro de um painel gerenciado pelo Herdr:

test "${HERDR_ENV:-}" = 1

Se a verificação falhar, informe que você não está executando dentro do Herdr e pare. Não inspecione ou controle a sessão focada do Herdr de fora do Herdr.

Quando a verificação passa, o binário herdr no PATH se comunica com a sessão atual. Use-o para inspecionar trabalhos vizinhos, criar layouts de terminal, iniciar agentes e comandos, ler saída e aguardar mudanças de estado.

Aprenda a CLI atual

O binário instalado é a autoridade para a sintaxe dos comandos. Comece com:

herdr --help

Em seguida, imprima o grupo de comandos relevante executando o grupo sem um subcomando:

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

Não execute herdr sem argumentos para descoberta; ele inicia ou anexa a TUI. Não investigue um comando mutável aninhado omitindo argumentos. Comandos como herdr workspace create são válidos com valores padrão e serão executados.

A maioria dos comandos de controle retorna JSON. Leia os identificadores e estados dessas respostas em vez de prevê-los.

Entenda layout, painéis e agentes

Escolha a primitiva que corresponde à tarefa:

• A topologia de workspace, aba e painel organiza locais de terminal.
• Comandos de painel controlam terminais brutos, shells, testes, servidores, entrada e saída.
• Comandos de agente controlam o agente de codificação reconhecido atualmente ocupando um painel.

Um painel existe mesmo que não contenha um agente. agent start requer um painel de shell disponível existente e nunca cria, divide ou move o layout. Use comandos de painel para processos comuns. Use comandos de agente quando o Herdr precisar validar a identidade do agente ou interpretar os estados de ciclo de vida idle, working, blocked, done e unknown.

Comandos de agente aceitam um nome único de agente ativo ou o ID do painel que atualmente hospeda esse agente. Eles não aceitam IDs de terminal ou rótulos genéricos de tipo de agente. Os nomes devem corresponder a [a-z][a-z0-9_-]{0,31} e ser únicos entre agentes ativos. Um nome segue o ocupante atual do painel e é limpo quando esse agente sai, é liberado ou substituído.

idle significa que o agente está pronto para entrada e sua aba foi vista na interface Herdr focada. done é o mesmo estado ocioso subjacente após trabalho em segundo plano não visto ser concluído. Focar a aba ou direcionar o painel ou agente com um comando de foco o marca como visto. Leituras da CLI não o marcam como visto. blocked significa que o Herdr reconheceu uma interface de aprovação ou pergunta. unknown significa que um agente está presente, mas o Herdr não consegue classificá-lo com confiança; isso não prova conclusão.

Use IDs e contexto do chamador

IDs públicos são identificadores opacos estáveis:

• workspace: w1
• aba: w1:t1
• painel: w1:p1

IDs de aba e painel fechados não são reutilizados. Um painel movido para outro workspace recebe um novo ID de painel qualificado pelo workspace. Após pane move, continue com .result.move_result.pane.pane_id ou o nome do agente ativo. O valor antigo é relatado como .result.move_result.previous_pane_id; apenas o contexto do chamador herdado do processo movido continua resolvendo esse ID antigo, então não o use como alvo geral de agente.

O Herdr injeta o contexto do chamador em cada painel gerenciado:

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

Prefira --current quando um comando de painel deve ter como alvo o painel chamador. Omitir um alvo pode usar o painel focado na interface, que pode pertencer ao usuário ou a outro cliente.

Descubra o estado ativo com:

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

As respostas de criação expõem os IDs a serem usados em seguida. workspace create retorna .result.workspace, .result.tab e .result.root_pane. tab create retorna .result.tab e .result.root_pane. pane split retorna o novo painel como .result.pane.

Inicie e coordene um agente

Por padrão, use um painel irmão na aba atual e o diretório de trabalho atual. Não crie um workspace, aba, worktree ou cwd diferente, a menos que o usuário solicite explicitamente essa topologia ou localização.

Respeite uma direção solicitada pelo usuário. Caso contrário, inspecione o painel chamador:

herdr pane layout --pane "$HERDR_PANE_ID"

Divida um painel largo para a direita e um painel estreito ou alto para baixo. Evite divisões repetidas na mesma direção que criam colunas muito estreitas ou linhas curtas. Mantenha o foco do usuário no painel chamador e preserve explicitamente o diretório de trabalho do chamador:

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

Substitua right por down quando apropriado. Leia o novo ID do painel de .result.pane.pane_id.

Um painel de shell disponível deve estar em seu prompt interativo, com o shell propriamente dito em primeiro plano e sem comando, editor ou agente em primeiro plano. Inicie um agente suportado nesse painel com um nome único útil:

herdr agent start reviewer --kind codex --pane <id-do-painel-retornado>

Use o tipo solicitado pelo usuário. Execute herdr agent para inspecionar a lista de tipos instalados e opções. Passe argumentos nativos do agente somente após --:

herdr agent start reviewer --kind codex --pane <id-do-painel-retornado> -- <argumentos-do-agente...>

agent start retorna somente após o Herdr detectar o agente esperado no mesmo painel e considerá-lo pronto para entrada interativa. O padrão é um tempo limite de inicialização de 30 segundos.

Envie trabalho através da superfície do agente:

herdr agent prompt reviewer "Revise o diff atual e relate apenas descobertas acionáveis." --wait --timeout 120000

agent prompt envia atomicamente o texto e Enter codificado, respeitando o modo bracketed-paste ativo do painel. Para trabalho normal de agente, --wait é suficiente: ele aguarda o primeiro estado idle, done ou blocked estabilizado. Não repita esses padrões com --until.

Um prompt enviado de um estado não trabalhando deve produzir uma mudança observada no ciclo de vida dentro de cinco segundos. Caso contrário, o Herdr retorna agent_prompt_stalled em vez de esperar indefinidamente. Essa espera rastreia o estado do ciclo de vida, não uma etapa individual; se o agente já estiver trabalhando, a conclusão da etapa ativa pode satisfazê-lo.

Use --until apenas para um fluxo de trabalho específico de estado, como aguardar um agente já em execução solicitar entrada:

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

Sem --until, agent wait independente usa os mesmos padrões de estado estabilizado que agent prompt --wait.

Use teclas lógicas para controles de interface interativos do agente:

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

O Herdr valida todas as teclas antes de escrever qualquer byte. Leia o resultado através do agente resolvido:

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

Se uma espera falhar ou retornar blocked, inspecione agent get e agent read antes de decidir qual entrada enviar. Use a superfície do painel apenas quando o controle bruto do terminal for intencional.

Execute um comando comum em outro painel

Crie um painel irmão com a mesma regra de geometria, preserve o diretório de trabalho do chamador e mantenha o foco do usuário inalterado:

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

Leia o novo ID do painel de .result.pane.pane_id, então execute e inspecione o comando:

herdr pane run <id-do-painel-retornado> "just test"
herdr pane wait-output <id-do-painel-retornado> --match "resultado do teste" --timeout 120000
herdr pane read <id-do-painel-retornado> --source recent-unwrapped --lines 120

pane run envia atomicamente o texto do comando e Enter. pane wait-output pesquisa o snapshot selecionado imediatamente, então a saída que já existe pode corresponder. Use --match <texto> para uma substring literal ou --regex <padrão> para uma expressão regular Rust. Omitir --timeout permite uma espera indefinida.

Use a fonte de leitura que corresponde à tarefa:

• visible: a janela de visualização atualmente renderizada.
• recent: saída renderizada recente, incluindo quebras suaves.
• recent-unwrapped: saída recente com quebras suaves unidas; prefira para logs e transcrições.
• detection: o snapshot do buffer inferior em texto simples usado para detecção de agente.

Use --format ansi quando cores e estilo de terminal são evidência. Caso contrário, use texto.

--lines pede ao Herdr por mais linhas da tela disponível do painel e do histórico de scrollback do host. Se aumentar não revelar mais de uma resposta concluída, o painel provavelmente está executando o agente na tela alternativa do terminal. Linhas que saem da tela alternativa não entram no histórico de scrollback do host do Herdr, então um número maior de linhas não pode recuperá-las.

Após essa leitura falhar, peça ao agente para escrever sua resposta completa como Markdown em um diretório temporário e responder apenas com o caminho do arquivo, então leia o arquivo diretamente. Use isso apenas como fallback; não solicite saída de arquivo no prompt inicial.

Regras de segurança e coordenação

• Use --no-focus para trabalho em segundo plano, a menos que o usuário tenha pedido para mudar de contexto.
• Use --current, um ID de painel explícito ou um nome único de agente. Não dependa do painel focado de outro cliente.
• Analise IDs de respostas JSON. Não os derive da ordem da barra lateral ou de exemplos.
• Não feche workspaces, abas, painéis ou sessões que você não criou, a menos que o usuário tenha solicitado explicitamente.
• Nunca execute herdr server stop de uma sessão ativa, a menos que o usuário pretenda explicitamente parar o servidor e seus processos de painel.
• Nunca mate o processo principal do Herdr. Use sessões de teste nomeadas para experimentos que precisam de um servidor isolado.
• Erros do servidor CLI são JSON em stderr com código de saída 1. Erros de sintaxe da CLI saem com código 2.

Expressões idiomáticas locais

A verificação HERDR_ENV=1 acima se aplica a controlar a sessão atual de dentro de um painel. Trabalho em nível de host — editar configuração, instalar plugins, depurar detecção de agente, construir automação em torno do socket/CLI — é legítimo de qualquer terminal. Para essas tarefas, leia references/local-idioms.md: configuração de entrega de notificação, manutenção de detecção de agente, metadados da barra lateral a partir de hooks do Claude Code, padrões de assinatura de evento, fluxo de worktree e notas de criação de plugin.