Ir para o conteúdo
Promovaweb

Claude Code, Codex e OpenCode dentro do Herdr

O Herdr reconhece agentes de código pelo processo em primeiro plano de cada painel e pelo que a ferramenta desenha no fim da tela. Para o Claude Code, o Codex e o OpenCode, a integração oficial instala um gancho na própria ferramenta, que reporta o estado da conversa e o identificador da sessão ao servidor do Herdr.

Três níveis de suporte

Qualquer ferramenta de terminal roda num painel do Herdr, inclusive um agente que o Herdr não conhece. O suporte de verdade aparece em camadas, cada uma com requisitos próprios. A documentação separa o que o Herdr faz com um agente em três capacidades diferentes:

  1. Executar

    claude

    O agente roda num painel como qualquer programa de terminal.

  2. Reconhecer o estado

    working · blocked · idle

    O Herdr identifica o agente e mostra o estado na barra lateral.

  3. Retomar a conversa

    claude --resume <id>

    Depois de reiniciar o servidor, o Herdr reabre a conversa do agente.

As três capacidades que o Herdr oferece a um agente de código. Cada uma depende da anterior e tem requisitos próprios.

Executar não exige nada além do agente instalado. O reconhecimento do estado vem dos manifestos de detecção que o Herdr carrega para cada ferramenta conhecida ou dos relatórios que a própria ferramenta envia. A retomada da conversa exige a integração oficial numa versão mínima, porque o Herdr precisa receber da ferramenta o identificador da sessão para montar o comando que reabre a conversa.

Os guias deste portal registram quais dessas capacidades foram conferidas. Nesta página, a conferência foi documental para as três capacidades, somada à execução de herdr integration status na máquina de referência, com o Herdr TUI 0.9.5.

Como o estado é detectado

Para as ferramentas suportadas pelo Herdr, o servidor encontra o processo do agente em cada painel e lê o fim da tela ao vivo, ignorando o trecho que você rolou para cima. Um manifesto de detecção compara essa tela com os padrões conhecidos daquela ferramenta e classifica o estado como idle, working ou blocked. Quando a integração da ferramenta também reporta o estado, o Herdr usa esses relatórios no lugar da leitura da tela.

Os manifestos vêm embutidos no binário. O Herdr também consulta o herdr.dev em busca de manifestos atualizados e aplica as atualizações válidas de cada agente sem reiniciar o servidor. A chave manifest_check = false, na seção [update] do arquivo de configuração, desliga essa consulta em segundo plano. Os manifestos locais, colocados na pasta de configuração da plataforma, substituem o embutido e o remoto.

Existe ainda um segundo grupo de ferramentas, que reportam o próprio estado ao Herdr sem precisar de integração instalada. A documentação 0.9.5 lista nesse grupo o Command Code, o Crush, o Kiro CLI, o Muse Code e o Prime Agent. Uma ferramenta desse grupo que também reporta o comando de retomada volta à mesma conversa depois de um reinício do servidor.

As integrações do Claude Code, do Codex e do OpenCode

O comando herdr integration install <alvo> instala a integração oficial de uma ferramenta. O comando herdr integration status mostra a situação de cada uma. Na máquina de referência, o status listou cada integração com a versão instalada e o arquivo que ela adicionou à ferramenta:

IntegraçãoO que fica instalado na ferramentaRetomada da conversa
herdr integration install claudeUm gancho em ~/.claude/hooks/herdr-agent-state.sh, versão 11 na máquina de referência.Exige a integração 6 ou mais nova e usa claude --resume <id>.
herdr integration install codexUm gancho em ~/.codex/herdr-agent-state.sh, versão 10 na máquina de referência.Exige a integração 5 ou mais nova e usa codex resume <id>.
herdr integration install opencodeUm plugin em ~/.config/opencode/plugins/herdr-agent-state.js, versão 13 na máquina de referência.Exige a integração 5 ou mais nova e usa opencode --session <id>.

O OpenCode está entre as ferramentas que também reportam o estado pela integração. No Claude Code e no Codex, o estado vem da leitura da tela e a integração acrescenta o identificador da sessão para a retomada. Depois de uma atualização do Herdr, uma integração antiga aparece como desatualizada no status. O mesmo herdr integration install reinstala a versão nova.

A lista completa da versão 0.9.5 inclui outras ferramentas com integração, como o GitHub Copilot CLI, o Cursor Agent CLI, o Gemini CLI, o Hermes Agent e o Kimi Code CLI, cada uma com o nível de suporte registrado na documentação oficial. O Amp, o Kiro CLI e o Maki têm só a leitura do estado, sem retomada.

Agentes em sandbox e em máquinas virtuais

No Linux e no macOS, um programa que envolve o agente, como uma sandbox, pode esconder do Herdr o processo verdadeiro. A variável HERDR_AGENT resolve esse caso: o comando HERDR_AGENT=claude fence -- claude diz ao Herdr que o processo em primeiro plano deve ser lido com o manifesto do Claude Code. A dica vale só para aquele processo. Quando o agente roda dentro de uma máquina virtual ou de um container, a variável definida lá dentro não chega ao Herdr, que fica no sistema hospedeiro.

Alguns ambientes Linux restritos não expõem o grupo de processos em primeiro plano do terminal. Para eles, o servidor aceita HERDR_PROCESS_DETECTION=child-groups, um modo opcional que deduz o agente pelos processos filhos. A documentação avisa que esse modo trabalha com o melhor esforço e pode confundir um processo em segundo plano mais recente com o processo em primeiro plano.

Avisos quando um agente termina

A barra lateral mostra o estado de todos os agentes, inclusive os de workspaces que você não está olhando. Para acompanhar sem olhar a tela, o Herdr oferece avisos e sons. A seção [ui.toast] da configuração escolhe a forma do aviso: desligado, um aviso dentro do próprio Herdr, uma notificação mostrada pelo terminal externo ou uma notificação enviada direto ao sistema operacional. A seção [ui.sound] emite um som quando um agente de um workspace em segundo plano muda de estado, com arquivos MP3 próprios para conclusão e para atenção necessária.

Os sons podem ser ligados ou desligados por agente. Por padrão, o Droid fica mudo. Os nomes das chaves, os valores aceitos e a forma de recarregar a configuração estão na página Personalização. A coordenação de agentes por script, com herdr agent start, herdr agent prompt e herdr agent wait, está na página Automação e plugins.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.