GUIA · 2026-08-31 · Por Borges Bot · 15 min de leitura

Herdr do zero: como trabalhar com coding agents sem perder o controle

Onboarding prático de Herdr para novos usuários: o problema que resolve, instalação, primeira sessão, estados de agente, panes, persistência, trabalho remoto em VPS e o encaixe com engenharia agêntica.

Neste artigo 24 seções

Um tutorial de onboarding. Este artigo unifica duas fontes — a sessão de engenharia agêntica do Kun Chen publicada no share.senge.io e o vídeo de introdução ao Herdr — verificadas contra a documentação oficial atual. Todo comando e atalho foi conferido nas docs oficiais; onde a explicação é inferência ou recomendação, está marcado.

O modelo mental do Herdr

Herdr
├── server / runtime  (roda em background)
│   └── session
│       └── workspace  (um por projeto)
│           ├── tab    (um por tipo de tarefa)
│           │   └── pane → process/agent
│           │   └── pane → agent
│           │   └── pane → shell (ex.: npm run dev)
│           └── status: working / blocked / idle / done

Herdr organiza processos numa hierarquia: uma session contém workspaces, cada workspace tem tabs, e cada tab pode ser dividido em panes. Um pane segura um processo — que costuma ser um coding agent, mas pode ser também seu servidor de desenvolvimento, um teste ou um shell comum. O sidebar mostra, para cada agente, working, blocked, idle ou done. É ele que responde à pergunta do começo deste artigo.

O problema que Herdr resolve

Você abriu quatro terminals. Um Claude Code está implementando. Outro está rodando testes. Um Hermes está pesquisando. E um quarto agente parou, esperando permissão para mexer num arquivo.

Para descobrir quem está trabalhando e quem só está esperando, não há caminho a não ser abrir terminal por terminal e olhar. Se você também trabalha com tabs espalhados, essa vistoria manual vira rotina — e rotina custa atenção.

A tese central deste artigo: Herdr não é outro coding agent. É o ambiente que mantém e organiza os coding agents que você já usa.

Antes dele:

terminal
├── agent 1
├── agent 2
├── agent 3
└── quem está travado?

Depois dele:

workspace Herdr
├── agent 1  [working]
├── agent 2  [blocked]
└── agent 3  [idle]

Você para de caçar o agente travado e passa a olhar um painel único.

O que Herdr não é

Herdr não substitui Claude Code, Hermes, Codex, Cursor Agent nem nenhum CLI de agente. Não é uma framework de agentes nem um modelo. Ele gera os processos, mantém os terminals abertos e relata o estado de cada um. A cadeia é:

Herdr → terminal/process → coding agent → model

Os agentes continuam sendo exatamente os executáveis que você já roda hoje. Herdr apenas os mantém vivos em segundo plano e torna o estado deles visível. Isso evita confusão arquitetural: você não está trocando de ferramenta, está mudando o runtime.

Instalando Herdr

A instalação oficial oferece caminhos equivalentes:

curl -fsSL https://herdr.dev/install.sh | sh

brew install herdr

mise use -g herdr

Há também um binário para Windows (beta, via PowerShell) e releases diretos no GitHub. O curl | sh é o método documentado oficialmente; se você prefere inspecionar antes, baixe o script e leia antes de executar — escolha sua própria barra de confiança. Verifique com:

herdr --version

Se imprimir um número de versão, o binário está instalado. Herdr é open source (Apache-2.0), um único binário em Rust, sem Electron. Roda em Linux, macOS e Windows (beta).

Primeira execução

Entre no diretório do projeto onde quer trabalhar e rode:

herdr

O que acontece: você não abre um "app". Inicia (ou se conecta a) um servidor Herdr em background e anexa seu terminal a ele. Se ainda não houver workspace, Herdr abre um automaticamente. Não há socket para você gerenciar — isso fica transparente.

O que observar: um layout com um workspace e um pane, com um sidebar. Se você já saiu de Herdr, o herdr reanexa você à mesma sessão, no mesmo estado.

Uma observação do vídeo que vale lembrar: Herdr é mouse-native. Se atalhos ainda não são naturais, comece clicando e usando o menu de contexto. O teclado é opcional e você pode migrar aos poucos.

Rodando seu primeiro agente

Dentro de um pane, inicie o agente que você já usa:

claude

Ou codex, pi, opencode, hermes, cursor — qualquer agente suportado. Herdr detecta o processo automaticamente e passa a mostrar esse pane como um agente no sidebar, com estado de vida.

Quando o agente está trabalhando, ele aparece em amarelo (working); quando termina, muda para azul (done) e, com notificações ativas, avisa você. Se o agente precisa de uma resposta sua, vira blocked.

O objetivo aqui não é ensinar Claude ou Hermes. É mostrar como um agente se comporta dentro de Herdr: ele fica na sua sessão, no seu pane, com histórico e estado preservados.

O único atalho que você precisa memorizar

Um multiplexer (e Herdr, embora não seja só isso, também é) senta entre seu terminal e os programas dentro dele. Esses programas já usam quase todas as teclas: Ctrl+C interrompe, Ctrl+R busca histórico, o editor reivindica o resto.

Se Herdr agarrasse teclas comuns diretamente, quebraria os programas dentro dele. A solução é um prefix key: aperte a tecla de prefixo — o padrão é Ctrl+B — e a próxima tecla vai para o Herdr em vez do agente. prefix+c significa "aperte Ctrl+B, solte, aperte c".

Ctrl+B, depois ? → abre a ajuda de atalhos. Memorize só este.

O prefixo é o que permite que um agente use Ctrl+D para o próprio processo, enquanto o Herdr usa Ctrl+B seguido de outra tecla para suas ações, sem conflito. Se nunca usou tmux, é só isso: o prefixo diz "o próximo comando é do multiplexer".

Cheat sheet (o essencial)

Estes são os atalhos confirmados na documentação atual. O resto fica no mouse.

Objetivo	Comando
Abrir ajuda de atalhos	`prefix+?`
Novo tab	`prefix+c`
Dividir para a direita	`prefix+v`
Dividir para baixo	`prefix+minus`
Mover entre panes	`prefix+h/j/k/l`
Navegar workspaces	`prefix+w`
Novo workspace	`prefix+shift+n`
Próximo / anterior tab	`prefix+n` / `prefix+p`
Zoom no pane focado	`prefix+z`
Fechar pane	`prefix+x`
Detach (deixa tudo rodando)	`prefix+q`

Para abrir as configurações, o vídeo aponta prefix+s. Tudo aparece também no prefix+?.

Working, blocked e idle

Cada agente tem um estado, e entender o que ele significa é o coração da ferramenta:

WORKING — o agente está executando trabalho agora.
BLOCKED — o agente parou e precisa de algo seu: uma decisão, permissão ou uma resposta.
IDLE — o processo está disponível, sem trabalho ativo.
DONE — o agente terminou a tarefa (quando aplicável).

Herdr mostra isso no sidebar, e a cor chama sua atenção só quando importa.

Vale saber como Herdr descobre isso, porque isso afeta a confiabilidade do sinal. Herdr usa duas fontes:

Lifecycle hooks/plugins (autoridade de estado) — certos agentes, como Pi, OMP, OpenCode e outros, têm uma integração instalada que relata o estado semanticamente. Quando ativa, esse estado é autoritativo — é o próprio agente dizendo "estou esperando decisão".
Screen manifest (fallback) — para agentes sem hooks completos (Claude Code, Codex, Hermes, Cursor), Herdr lê uma foto da parte de baixo da tela e classifica working/blocked/idle por heurística.

A distinção importa: detecção por tela é heurística e menos confiável que um lifecycle hook explícito. Um agente pode ter estado ambíguo se a interface não der indícios claros. Se o estado parecer errado, confirme que o agente roda dentro de Herdr e que a integração foi instalada.

Para instalar uma integração (confirmado nas docs):

herdr integration install <agente>   # ex.: herdr integration install hermes

Para ver o que Herdr enxerga:

herdr agent list
herdr pane read w1:p1 --source recent --lines 50

Não fique olhando para os agentes

O modo de trabalho que Herdr habilita é: delegue, saia, deixe a notificação avisar quando houver bloqueio ou conclusão.

As notificações ficam nas configurações (prefix+s): som, toast no canto ou notificação de sistema. Costumam estar desligadas por padrão, então configurar uma vez é esperado. Mas a mudança que vale mais que a configuração é o comportamento: delegar → sair → notificação → voltar só quando estiver blocked ou done.

Feche o terminal. O trabalho continua.

Esta é a diferença estrutural: a UI do terminal não é o ciclo de vida do agente.

Herdr é um servidor em background; os terminals vivem dentro dele. Então:

prefix+q (ou fechar a janela) → detach: o cliente sai, mas o servidor e cada agente continuam rodando.
herdr novamente → reattach: você volta à mesma sessão, com o processo nunca tendo parado.

Isso cobre fechar o terminal, perder a conexão SSH ou desligar o laptop: os agentes seguem onde estavam.

Precisão importante, para não superprometer: a persistência total depende da máquina onde o servidor roda. Se o servidor Herdr for morto (queda de energia, crash), os processos terminam — porque viviam ali. O que sobrevive a um restart é o layout (workspaces, tabs, panes, diretórios). Para retomar conversas após restart, Herdr relança panes que têm uma integração de sessão nativa (Claude Code, Codex, Hermes, Pi etc. reportam a sessão e o Herdr a reabre). A restauração de histórico de tela é experimental e desligada por padrão, porque o output pode conter segredos.

Resumindo: com servidor estável, fechar terminal → OK, trabalho continua. Matar o servidor → layout volta, processos não. Para tarefas longas críticas, rode Herdr numa máquina que não vai cair.

Rodando agentes em outra máquina

Este é o uso mais relevante para um fluxo com VPS. O padrão é: UI local, processos remotos.

LAPTOP
  Herdr UI (cliente fino)
     │  SSH
     ▼
VPS / workstation
  Herdr runtime
  ├── Hermes
  ├── Claude
  └── outros agentes

Instale Herdr na máquina onde o trabalho vai rodar e, do laptop, conecte como cliente fino:

herdr --remote ssh://voce@sua-vps:2222

Para destinos recorrentes no ~/.ssh/config, use o nome curto:

herdr --remote nome-do-host

Isso significa: o binário local é um cliente fino para o servidor Herdr remoto. Os agentes rodam na VPS; a interface aparece no seu terminal, sem a latência de abrir a UI inteira via SSH. Atalhos locais e recursos como colar uma imagem do clipboard local num agente remoto continuam funcionando. Na primeira conexão, Herdr pode pedir para instalar o runtime no remoto.

Persistência remota funciona como a local, com uma vantagem extra: você pode desligar o laptop, e os agentes seguem na VPS. Dá até para conectar de um telefone por SSH.

Um cenário concreto com VPS

notebook
  └── Herdr (client local)
        │
        ▼
VPS
   ├── pane: coding agent (implementa)
   ├── pane: test agent (roda testes)
   └── pane: research agent (pesquisa)

Por que isso é útil:

O notebook pode desligar; o trabalho pesado fica na VPS que não cai.
As sessões ficam organizadas numa hierarquia única, não espalhadas por SSH e tmux avulsos.
Bloqueios ficam visíveis no sidebar: se o implementer está blocked, você sabe que precisa decidir algo, mesmo do celular.

Fluxo de detach/reconnect remoto:

# no laptop, anexar à sessão remota
herdr --remote nome-do-host

# desconectar (agentes continuam na VPS)
# prefix+q

# reconectar depois
herdr --remote nome-do-host

Para listar sessões abertas, o vídeo mostra herdr session list. Isto não é um guia de provisioning de VPS — é o encaixe do Herdr nesse cenário.

Da execução à engenharia agêntica

Aqui as duas fontes deste artigo se encontram.

O que Herdr resolve sozinho é a camada operacional:

ciclo de vida de processo — os agentes ficam vivos em background;
visibilidade — working/blocked/idle agregado, sem vistoria manual;
gerenciamento de sessão — layout, workspaces, tabs, panes, reattach.

O que a engenharia agêntica resolve — o tema da sessão do Kun Chen — é a camada de arquitetura:

decomposição — dividir um problema grande em tarefas;
responsabilidade — papel de cada agente;
contexto — qual informação cada um recebe;
ferramentas e validação — como executam e como se checa o resultado;
coordenação — quem espera o quê.

A regra:

Herdr não é uma arquitetura de agentes. É o runtime/ambiente operacional onde parte dela roda.

No fluxo do Kun Chen, um único orquestrador recebe a ideia, delega scouts de pesquisa em paralelo, depois o implementer e a revisão. Herdr não é esse orquestrador — mas é onde esses agentes vivem, são observados e coordenados ao nível de processo. Você constrói a arquitetura agêntica; Herdr dá o palco.

Primeiro workflow multi-agente

Você não precisa começar com dez agentes. Um exemplo enxuto:

WORKSPACE: feature-login
  Pane 1  IMPLEMENTER → implementa a feature
  Pane 2  REVIEWER    → revisa o diff
  Pane 3  TESTER      → roda os testes

Defina antes de começar:

Papel	Input	Responsabilidade	Output	Done when
Implementer	spec da feature	escrever o código	diff	feature compila / testes passam
Reviewer	diff	revisar arquitetura e riscos	feedback	sem bloqueio material
Tester	código + spec	rodar testes relevantes	resultado	suíte verde

Com Herdr, você observa de longe: cada papel é um pane, cada pane tem seu estado. Quando o reviewer fica blocked pedindo sua decisão, você atende. O done do tester é o sinal para seguir. O vídeo faz exatamente essa distribuição — implementer, reviewer, servidor — e serve de molde para o primeiro dia.

Não confunda paralelismo com multi-agent

Três agentes rodando ao mesmo tempo não é, por si só, boa engenharia multi-agent.

A pergunta antes de abrir panes e dividir trabalho: há vantagem concreta em especialização, isolamento, paralelismo ou revisão? Se não, um único agente resolve melhor — menos contexto dividido, menos interfaces, menos risco de dois agentes pisarem nos mesmos arquivos.

Herdr torna tentador abrir dez panes. Use com critério. Multi-agent compensa quando o custo de coordenação é menor que o benefício de rodar coisas independentes.

A skill oficial do Herdr

Herdr expõe uma CLI e um socket que agentes podem usar, e há uma skill oficial para ensinar um agente a operar Herdr:

agent → Herdr CLI/socket → criar pane → iniciar outro agente → observar

Instalação:

npx skills add herdrdev/herdr --skill herdr -g

-g instala global; sem ele, no projeto. Você também pode imprimir a cópia que acompanha seu binário com herdr --skill. Para agentes sem sistema de skill, cole o arquivo nas instruções.

A skill tem um guardrail de segurança: só age quando HERDR_ENV=1 está definido — ou seja, só quando o agente está dentro de um pane gerenciado por Herdr. Isso impede um agente externo de controlar uma sessão que não é dele.

Com a skill, o agente pode: inspecionar workspaces e panes, dividir panes, rodar comandos sem roubar foco, ler saída de agentes irmãos, esperar outra tarefa terminar e iniciar agentes auxiliares. Isso é poderoso e envolve risco. Não instale a skill no primeiro dia; primeiro entenda o que ela libera.

Agentes controlando agentes

Isso forma uma progressão:

Nível 1 — o humano gerencia panes.
Nível 2 — o humano delega tarefas para vários agentes.
Nível 3 — o agente cria e coordena outros agentes via Herdr.

Domine os Níveis 1 e 2 antes do 3. O motivo: quando os agentes começam a orquestrar outros, a observabilidade e a capacidade de diagnóstico diminuem. Você passa a ler um resumo do que aconteceu em vez de ver o que aconteceu. Não é motivo para evitar o Nível 3 — é um aviso para ir com os fundamentos sólidos.

Herdr + Hermes

O Hermes Agent é um agente suportado por Herdr:

herdr integration install hermes

Há uma distinção a não confundir:

Agente suportado — Hermes é detectado e roda dentro de um pane, com estado por screen manifest e restauração de sessão.
Integração profunda — não invente uma integração específica que não existe. Herdr trata Hermes, na prática, como um CLI de agente de novo: executa, detecta e gerencia a sessão. O que existe é a skill oficial e a integração de sessão comum.

Na prática, isso cobre um fluxo útil: um workspace por área.

Herdr
├── Hermes / research
├── Hermes / implementation
└── Hermes / validation

Workflow recomendado para quem está começando

Avance em etapas, não em dias de calendário:

Etapa 1 — um agente. Aprenda a abrir, navegar, prefix+q (detach) e herdr (reattach). Entenda os estados no sidebar e onde fica o prefix+?.
Etapa 2 — dois agentes independentes. Aprenda panes, notificações e a identificar um agente blocked sem vistoria manual.
Etapa 3 — remoto. Execute um agente noutra máquina com herdr --remote; desligue o laptop e religue a sessão.
Depois — coordenação. Introduza papéis (reviewer, tester), a skill do Herdr e orquestração entre agentes.

Cada etapa deve ser pequena e completa. O objetivo é reproduzir um fluxo cotidiano estável, não "usar todos os recursos".

Exercício: sua primeira feature com Herdr

Objetivo simples: adicionar uma página /health a uma aplicação local. O foco é Herdr, não a aplicação.

Na pasta do projeto, rode herdr.
Crie um workspace para a feature (um projeto ativo = um workspace).
Inicie o agente implementer num pane (seu CLI de agente preferido).
Delegue: "adicione uma página /health que retorne {status: ok}".
Abra um segundo pane (prefix+v ou prefix+minus) e inicie o reviewer.
Passe o diff/contexto para o reviewer.
Observe o sidebar: implementer → working, depois done; reviewer → working.
Responda ao blocked quando um agente pedir decisão.
Valide o resultado (teste a rota).
prefix+q para detach — tudo continua rodando.
herdr novamente: reattach e confirme que a sessão voltou como estava.

Quando o ciclo terminar, você terá navegado por workspace, tab, pane, estado de agente, detach e reattach — o essencial.

Troubleshooting

Casos comuns com diagnóstico e correção:

O agente não muda de estado

Causa provável: estado baseado em screen manifest, e o agente não emite indício claro.
Teste: herdr agent list e herdr pane read <pane> --source recent --lines 50.
Correção: confirme que o agente roda dentro do Herdr e que a integração está instalada (herdr integration status). Se o agente não tem hooks completos, aceite o limite da heurística.

Remote lento

Causa provável: você iniciou a interface Herdr no servidor via SSH e o terminal está streaming a UI remota.
Correção: use herdr --remote <host> para executar um cliente local conectado ao servidor remoto.

A sessão "desapareceu"

Causa provável: restart do servidor Herdr matou os processos.
Correção: rode herdr na mesma pasta para reanexar; o layout volta. Para conversas, verifique se o agente tem integração de sessão nativa habilitada (resume_agents_on_restore é default true). Para processos longos críticos, não mate o servidor.

Notificações não aparecem

Causa provável: desligadas por padrão.
Correção: em prefix+s, ative toast/sistema e som. Configurar uma vez é esperado.

Atalho não funciona

Causa provável: você apertou a tecla sem o prefixo, e ela foi para o agente.
Correção: Ctrl+B primeiro, depois o comando. Confira a tabela e o prefix+?.

Agente CLI não detectado

Causa provável: agente "detectado mas pouco testado", ou não lançado dentro de Herdr.
Correção: agentes suportados são detectados ao rodar dentro de um pane. Não-suportados rodam normalmente, só sem estado rico.

Limitações honestas

Herdr é um projeto ativo e em evolução (versões v0.8.x à época desta escrita):

O estado de alguns agentes depende de heurística de tela, menos confiável que hooks de lifecycle. Para agentes com integração completa (Pi, OMP, etc.), o estado é autoritativo; para o resto, é boa estimativa.
A persistência total vale enquanto o servidor rodar. Restart de servidor = processos morrem, layout volta, conversa só reabre com integração de sessão nativa.
Remote depende de SSH estável e pode exigir ajustes de firewall/porta.
A restauração de histórico de tela é experimental e desligada por padrão (proteção a segredos).
Orquestração por agentes (Nível 3) aumenta poder, mas diminui observabilidade — use com maturidade, não no primeiro dia.

Fontes

Kun Chen, construção de app full-stack com engenharia agêntica — share.senge.io/relatorios (2026) — modelo mental de engenharia agêntica, workflows e coordenação.
Vídeo de introdução ao Herdr — youtu.be/Ct-mtWqV3Ro — tour, prefixo, notificações, remote e skill oficial.
Documentação oficial do Herdr (herdr.dev/docs) — quick start, keyboard, session-state, agents, integrations, agent-skill — fonte de verificação de comandos, atalhos, estados, remote e suporte de agentes na versão atual.

(Onboarding prático derivado das fontes acima, verificado contra a documentação atual. Inferências e recomendações estão sinalizadas no corpo; comandos e atalhos dependentes de versão devem ser confirmados com herdr --version e as docs associadas.)