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:
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:
Iniciar
herdr agent startAbre o agente num painel livre e espera ele ficar pronto.
Enviar a tarefa
herdr agent prompt --waitEscreve o texto com Enter e espera a atividade começar.
Esperar o estado
herdr agent waitVolta quando o agente fica idle, done ou blocked.
Ler o resultado
herdr agent readLê a saída recente do terminal do agente.
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.