Ir para o conteúdo
Promovaweb

Automação, Socket API e plugins do Herdr

O servidor do Herdr TUI expõe uma Socket API local. Os comandos herdr workspace, herdr pane e herdr agent são atalhos de linha de comando sobre essa API. Com eles, um script ou outro agente cria workspaces, inicia agentes, envia tarefas, espera mudanças de estado e lê a saída dos terminais. Os plugins usam a mesma linha de comando, declarados num manifesto herdr-plugin.toml.

Três camadas sobre o mesmo controle

A documentação separa três formas de controlar um servidor do Herdr, todas apoiadas na mesma superfície de controle. A skill do agente ensina um agente de código, como o Claude Code, a usar o Herdr de dentro de um painel. Os comandos da linha de comando atendem scripts de shell, coordenação simples e conferência manual. A Socket API crua atende ferramentas próprias, clientes do protocolo e programas que assinam eventos por tempo longo.

O comando herdr api schema imprime o esquema do protocolo embutido no binário instalado. Com --json, sai o documento JSON Schema completo, com requisições, respostas, erros e eventos. Com --output, o documento é gravado num arquivo. O comando herdr api snapshot mostra o estado ao vivo da sessão. A skill do Herdr TUI, impressa por herdr --skill, está explicada na página Skill do Herdr TUI.

Layout, painel e agente

A automação do Herdr trabalha com três primitivas. A escolha entre elas define o que o comando confere antes de agir:

PrimitivaPara que serveComandos de exemplo
LayoutCriar e arrumar os lugares dos terminais: workspaces, abas e divisões.herdr workspace create, herdr tab create e herdr pane split.
PainelControlar um terminal cru, com qualquer processo: rodar comandos, enviar teclas, ler e esperar saída.herdr pane run, herdr pane send-keys, herdr pane read e herdr pane wait-output.
AgenteControlar um agente reconhecido pelo nome ou pelo painel, com o estado dele.herdr agent start, herdr agent prompt, herdr agent wait e herdr agent read.

O painel existe com ou sem agente. O agente é o processo reconhecido que ocupa o painel naquele momento. Por isso a entrada pelo painel vai para o terminal seja qual for o processo, enquanto a entrada pelo agente confere se aquele agente ainda controla o painel e recusa o envio quando outro processo tomou o lugar. Testes, servidores de desenvolvimento e observadores de CI usam os comandos de painel. Os comandos de agente entram quando o script precisa saber qual agente está ali e se ele está working, blocked, done, idle ou unknown.

Os comandos de criação devolvem JSON com os identificadores do que criaram. O workspace create devolve o workspace, a primeira aba e o painel raiz. O pane split devolve o painel novo. O script lê esses identificadores da resposta, sem prever valores como w1:p2 a partir da ordem da barra lateral.

Um agente coordenado por script

O ciclo completo de uma tarefa delegada passa por quatro comandos. O herdr agent start reviewer --kind codex --pane <id> inicia um agente suportado num painel que está no prompt do shell e só retorna quando o Herdr detecta o agente pronto para receber texto, com espera padrão de 30 segundos:

  1. Iniciar

    herdr agent start

    Abre o agente num painel livre e espera ele ficar pronto.

  2. Enviar a tarefa

    herdr agent prompt --wait

    Escreve o texto com Enter e espera a atividade começar.

  3. Esperar o estado

    herdr agent wait

    Volta quando o agente fica idle, done ou blocked.

  4. Ler o resultado

    herdr agent read

    Lê a saída recente do terminal do agente.

O ciclo de uma tarefa delegada a um agente pelo Herdr TUI. Cada etapa devolve JSON com o agente e o estado atual.

O agent prompt com --wait exige atividade observada depois do envio. Quando o agente não sai do estado anterior em até cinco segundos, o comando devolve agent_prompt_stalled. Quando o agente já está em blocked, o envio é recusado com agent_blocked antes de qualquer texto chegar ao terminal. A resposta à janela de aprovação fica para agent send-keys, depois da leitura da tela.

Os nomes de agente seguem o formato [a-z][a-z0-9_-] com até 32 caracteres e valem enquanto aquele agente ocupa o painel. Os identificadores e os nomes pertencem a um servidor. Para controlar uma máquina cadastrada, o prefixo herdr --machine <rótulo> acompanha todos os comandos, da listagem ao envio. Os identificadores locais não servem para os painéis remotos.

Plugins como pastas com manifesto

Um plugin do Herdr é uma pasta com o manifesto herdr-plugin.toml e os comandos que o Herdr executa. O plugin pode ser um script Bash, um app JavaScript, um binário Rust ou qualquer programa que a máquina roda. O Herdr cuida da instalação, da validação do manifesto, dos atalhos, dos painéis, dos eventos e do acesso ao socket, enquanto o plugin cuida da linguagem, das dependências e dos próprios arquivos de estado.

Não existe um kit de desenvolvimento separado. A linha de comando inteira do Herdr funciona como a interface dos plugins, chamada pelo caminho da variável HERDR_BIN_PATH, que aponta para o binário em execução. O manifesto declara o que o plugin oferece:

  • [[actions]]Uma ação com título e comando, chamada pela interface ou por atalho.
  • [[events]]Um comando disparado por um evento do servidor, como worktree.created.
  • [[panes]]Um painel do plugin, aberto sobreposto ou no layout.
  • [[startup]]Um comando que roda quando o servidor inicia.
  • [[build]]Os comandos de construção executados na instalação.
  • [[link_handlers]]Uma ação disparada por links que seguem um padrão.

O topo do manifesto exige id, name, version e min_herdr_version. O Herdr recusa o plugin quando a versão mínima é mais nova que o binário instalado. Os comandos são listas de argumentos, executadas sem shell, de modo que nenhuma expansão de variável acontece sem um shell iniciado de propósito pelo próprio comando. O tutorial Crie um plugin com ação e evento mostra um exemplo pequeno em Node.js. O catálogo de plugins reúne os plugins da comunidade testados para o portal.

Instalação, atualização e confiança

O comando herdr plugin install <dono>/<repositório>/<pasta> aceita só o formato abreviado do GitHub. Ele clona o repositório com o Git, mostra uma prévia da origem e dos comandos num terminal interativo, constrói numa pasta gerenciada pelo Herdr e registra o plugin. O herdr plugin link <pasta> liga uma pasta local durante o desenvolvimento. O herdr plugin update busca de novo a referência gravada na instalação e pula os commits que não mudaram. Os plugins instalados valem para o usuário em todas as sessões do Herdr.

Essa mesma superfície de controle permite coordenar implementação e revisão entre dois agentes, cada um no próprio painel ou worktree, com um script que inicia os dois, envia as tarefas e lê os resultados. O Herdr Core oferece um modelo de coordenação parecido pelo comando hc, com hc run, hc send, hc wait e hc read, explicado na página Herdr Core.

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.