Herdr — onde seus agentes de código moram (e continuam trabalhando quando você fecha o terminal)
Se você usa agente de código com frequência, provavelmente já viveu essa cena: três terminais abertos, um Claude Code implementando uma feature, um Codex revisando outra branch, um OpenCode investigando um bug. Você vai tomar um café. Quando volta, dois estão parados esperando você aprovar alguma coisa há 15 minutos, e um terminou faz tempo sem você perceber.
Ou pior: você fecha o terminal sem querer, a conexão SSH cai, e a sessão inteira vai junto.
O Herdr resolve exatamente isso. Ele se descreve como "onde seus agentes de código moram": um runtime de terminal que mantém os agentes rodando em segundo plano, mostra o estado de cada um e expõe uma API pra que scripts (e outros agentes) controlem tudo.
O que é o Herdr (em 30 segundos)
Pense num tmux feito para agentes de código. É um binário único em Rust, sem Electron, que roda dentro do terminal que você já usa.
O que ele faz:
- Mantém tudo rodando em segundo plano. Os terminais vivem num servidor local. Você fecha a janela, perde a conexão, e os agentes continuam trabalhando. Rodou
herdrde novo, está tudo lá. - Mostra o estado de cada agente. Ele lê cada painel e marca o agente como
working,blocked,doneouidle. Nada de caçar qual terminal está travado esperando aprovação. - Funciona com o agente que você já usa. São mais de vinte agentes suportados, incluindo Claude Code, Codex, Cursor CLI, OpenCode, Gemini e Copilot. Ele não substitui nem "embrulha" o agente; ele só é dono do terminal onde o agente roda.
- Junta várias máquinas numa janela só. Notebook, desktop e servidor remoto via SSH, com os agentes de todos aparecendo lado a lado.
- Tem CLI e API de socket. Tudo que você faz com o mouse dá pra fazer por script. E os próprios agentes podem usar essa API pra abrir painéis, iniciar outros agentes e esperar um terminar.
É open source (Apache 2.0) e, no momento em que escrevo, está na versão 0.9.3.
Instalação
# macOS / Linux
curl -fsSL https://herdr.dev/install.sh | sh
# Homebrew
brew install herdr
# mise
mise use -g herdr
No Windows, pelo PowerShell:
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
O suporte nativo a Windows (via ConPTY) já é estável, mas a própria documentação avisa que alguns recursos se comportam diferente de Linux e macOS.
Primeiros passos
Entre na pasta do projeto e rode:
herdr
Pronto. Ele sobe o servidor em segundo plano (ou se conecta ao que já está rodando) e abre um workspace pro projeto. Dentro dele, rode o agente normalmente:
claude
O Herdr detecta o agente sozinho e passa a mostrar o estado dele na barra lateral.
Alguns conceitos que valem saber:
| Conceito | O que é |
|---|---|
| Workspace | Container de um projeto. Um por repositório, tarefa ou investigação. |
| Tab | Um layout dentro do workspace: agentes, logs, servidor, review. |
| Pane | Um terminal de verdade. Pode ter um shell, um servidor ou um agente. |
| Agent | O agente reconhecido rodando dentro de um pane, com estado. |
Ele é pensado pra mouse (clicar, arrastar divisória, menu com botão direito), mas os atalhos seguem o estilo do tmux, com prefixo ctrl+b:
| Ação | Atalho |
|---|---|
| Dividir à direita | ctrl+b v |
| Dividir pra baixo | ctrl+b - |
| Nova tab | ctrl+b c |
| Próxima / anterior | ctrl+b n / p |
| Navegar workspaces | ctrl+b w |
| Ver todos os atalhos | ctrl+b ? |
| Sair sem parar nada | ctrl+b q |
O ctrl+b q é o que muda o jogo. Você desconecta, os agentes continuam. Pra voltar, herdr de novo. Pra parar tudo de verdade:
herdr server stop
Os quatro estados
Essa é a parte que mais faz diferença no dia a dia. Cada agente aparece com um estado:
| Estado | Significado |
|---|---|
working | Está trabalhando. |
blocked | Precisa de você: aprovação, pergunta, decisão. |
done | Terminou e você ainda não olhou. |
idle | Terminou e você já viu, ou está esperando input. |
Com cinco agentes rodando, você não precisa mais olhar terminal por terminal. Bateu o olho na barra lateral, viu quem está blocked, resolve só aquele.
E dá pra receber notificação quando algum agente termina ou trava. No ~/.config/herdr/config.toml:
[ui.toast]
delivery = "system" # herdr, terminal, system ou off
position = "bottom-right"
Com system, a notificação vai pro sistema operacional. Você pode estar em outra janela ou numa reunião e ainda assim saber que um agente precisa de você.
Rode herdr --default-config > ~/.config/herdr/config.toml pra começar com a configuração padrão completa, e herdr server reload-config pra aplicar mudanças sem reiniciar nada.
Exemplo real 1: um workspace por tarefa, com worktrees
No post de Claude Code eu mostrei como usar git worktree pra rodar duas sessões em paralelo, cada uma na sua branch. O Herdr transforma isso num comando só:
herdr worktree create --branch feat/auth-refresh --no-focus
herdr worktree create --branch fix/payment-null --no-focus
Cada comando cria o checkout da branch e abre um workspace pra ele, agrupado com o workspace principal do repositório. Aí é só entrar em cada um e rodar o agente.
Quando terminar, remova o checkout (a branch não é apagada):
herdr worktree remove --workspace <workspace-id>
Exemplo real 2: rodar teste e esperar o resultado
O Herdr não serve só pra agentes. Qualquer processo pode rodar num pane e ser observado:
herdr pane run w1:p3 "pnpm test --watch"
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
O wait-output bloqueia até aparecer o texto (ou bater o timeout). Dá pra usar isso pra encadear passos: subir o servidor, esperar o ready, rodar os testes de integração.
E pra ler a saída de qualquer pane sem precisar estar olhando pra ele:
herdr pane read w1:p3 --source recent-unwrapped --lines 120
Exemplo real 3: um script que pede review de outro agente
Aqui começa a parte mais interessante. Toda a CLI devolve JSON, então dá pra automatizar o fluxo inteiro com jq.
Esse script abre um pane ao lado do atual, inicia um Codex como revisor, manda ele revisar o diff contra a main, espera terminar, salva o resultado e te notifica:
#!/usr/bin/env bash
# scripts/review.sh
set -euo pipefail
# Só funciona dentro de um pane do Herdr
test "${HERDR_ENV:-}" = 1 || { echo "Rode dentro do Herdr."; exit 1; }
# Abre um pane à direita, no mesmo diretório, sem tirar seu foco
split=$(herdr pane split --current --direction right --cwd "$PWD" --no-focus)
pane=$(jq -r '.result.pane.pane_id' <<< "$split")
# Inicia o Codex nesse pane com o nome "revisor"
herdr agent start revisor --kind codex --pane "$pane"
# Manda a tarefa e espera ele terminar (até 10 minutos)
herdr agent prompt revisor \
"Revise as mudanças desta branch contra a main (git diff main). \
Liste apenas problemas acionáveis: bugs, edge cases, segurança. \
Não refatore nada." \
--wait --timeout 600000
# Salva a resposta e avisa
herdr agent read revisor --source recent-unwrapped --lines 200 > review.md
herdr notification show "Review pronta" --body "Veja review.md" --sound done
Alguns detalhes que importam:
--no-focusmantém você no pane em que está. O revisor trabalha ao lado sem te interromper.- IDs vêm do JSON. Nunca tente adivinhar que o próximo pane vai ser
w1:p2; leia da resposta. agent startsó volta quando o agente está pronto pra receber prompt. Não precisa desleep.agent prompt --waitespera o agente sair deworking. Se ele parar emblocked(pedindo aprovação), o comando volta e você decide o que fazer.
E se o revisor travar pedindo algo, dá pra ver o que é e responder:
herdr agent wait revisor --until blocked --timeout 120000
herdr agent read revisor --source recent-unwrapped --lines 80
herdr agent send-keys revisor esc
Exemplo real 4: um agente coordenando outro
O script acima funciona, mas dá pra ir além: o próprio agente pode usar o Herdr.
O Herdr distribui uma skill que ensina qualquer agente a usar a CLI:
npx skills add herdrdev/herdr --skill herdr -g
Com ela instalada, você abre o Claude Code dentro do Herdr e pede em linguagem natural:
Use o herdr para abrir um Codex num pane ao lado com o nome "revisor".
Quando eu terminar esta feature, peça para ele revisar o diff contra a main
e me traga só os problemas que ele encontrar.
O Claude Code abre o pane, inicia o Codex, manda o prompt, espera e lê a resposta. Tudo pelos mesmos comandos do exemplo anterior.
A skill tem uma trava de segurança que eu gosto: ela só funciona se a variável HERDR_ENV=1 estiver definida, o que só acontece dentro de um pane gerenciado pelo Herdr. Um agente rodando fora dele não consegue controlar a sua sessão.
Isso conversa diretamente com o que escrevi sobre harness engineering: o review por um agente com contexto limpo, que não viu a implementação sendo feita, é um dos melhores sensores que existem. Com o Herdr, ele vira parte do fluxo, não um passo manual.
Exemplo real 5: agentes em outra máquina
Tem um servidor com mais CPU, ou uma máquina que fica ligada o dia todo? Adicione ela via SSH:
herdr machine add workbox --label "Servidor de build"
Os workspaces e agentes dessa máquina aparecem na mesma janela, junto com os locais. Você fecha o notebook, os agentes no servidor continuam. Abre de novo no dia seguinte, reconecta e está tudo lá.
E a CLI funciona remotamente também:
herdr --machine "Servidor de build" agent list
herdr --machine "Servidor de build" agent prompt revisor "Qual o status?" --wait --timeout 120000
O Herdr não guarda senha nem chave: ele usa o SSH que você já tem configurado.
Exemplo real 6: sobreviver a um restart
Detach e reattach não perdem nada, porque os processos nunca param. Mas se o servidor do Herdr reiniciar (ou a máquina), os processos originais morrem. O Herdr restaura o layout (workspaces, tabs, panes, diretórios), mas não a conversa do agente.
Pra isso existem as integrações:
herdr integration install claude
herdr integration install codex
herdr integration install opencode
Com a integração instalada, depois de um restart o Herdr reabre a mesma sessão do agente, de onde ela parou. Também dá pra instalar pelas configurações, na aba de integrações, que já sugere as que fazem sentido pros agentes encontrados no seu PATH.
Exemplo real 7: um plugin com atalho
Se você roda o script de review sempre, vale transformar num plugin com atalho de teclado. Um plugin é uma pasta com um manifesto e um executável:
review-plugin/
herdr-plugin.toml
review.sh
# herdr-plugin.toml
id = "tautorn.review"
name = "Review"
version = "0.1.0"
min_herdr_version = "0.7.0"
platforms = ["linux", "macos"]
[[actions]]
id = "review-diff"
title = "Pedir review do diff"
contexts = ["workspace"]
command = ["bash", "review.sh"]
O review.sh é quase o mesmo script do exemplo 3, com três ajustes pro contexto de plugin:
#!/usr/bin/env bash
# review.sh
set -euo pipefail
herdr="$HERDR_BIN_PATH" # o binário do Herdr em execução
# Sem --current e sem --cwd: o plugin roda na pasta dele, não na do projeto.
# Sem alvo, o split usa o pane focado, e o novo pane herda o diretório dele.
split=$("$herdr" pane split --direction right --no-focus)
pane=$(jq -r '.result.pane.pane_id' <<< "$split")
"$herdr" agent start revisor --kind codex --pane "$pane"
"$herdr" agent prompt revisor \
"Revise as mudanças desta branch contra a main (git diff main). \
Liste apenas problemas acionáveis: bugs, edge cases, segurança." \
--wait --timeout 600000
"$herdr" notification show "Review pronta" --body "Veja o pane do revisor" --sound done
Os ajustes: o binário vem de HERDR_BIN_PATH, o split não usa --current nem --cwd (o processo do plugin roda na pasta do plugin, não na do projeto), e o resultado fica no pane do revisor em vez de num arquivo. Pra testar localmente:
herdr plugin link ./review-plugin
E o atalho, no config.toml:
[[keys.command]]
key = "prefix+r"
type = "plugin_action"
command = "tautorn.review.review-diff"
description = "pedir review"
Agora ctrl+b r dispara o review. Tem um marketplace com mais de mil plugins prontos, vale dar uma olhada antes de escrever o seu.
Pontos de atenção
Fechar o notebook não é fechar o terminal. Se os agentes rodam na sua máquina e ela entra em suspensão, eles param junto. Pra trabalho que precisa seguir com o notebook fechado, rode os agentes numa máquina que fica ligada e conecte via herdr machine add.
Restart não é detach. Desconectar mantém tudo vivo. Reiniciar o servidor ou a máquina mata os processos; o layout volta, e a conversa só volta se você instalou a integração do agente. Servidor de dev e teste em watch precisam ser iniciados de novo.
Cada agente gasta token. Cinco agentes em paralelo são cinco vezes o consumo. Paralelizar é ótimo pra tarefas independentes; pra tarefa que depende uma da outra, você só multiplica custo e conflito de merge.
Não automatize aprovação. Dá pra responder um agente blocked com send-keys, mas o blocked existe justamente pra você decidir. Um script que aprova tudo automaticamente desliga a principal proteção que você tem.
Agente controlando agente amplia o alcance. Um agente com a skill do Herdr pode iniciar outros agentes, rodar comandos em outros panes e ler a saída deles. Isso é poderoso, e é por isso que as permissões e o sandbox do agente principal importam ainda mais.
Ainda é versão 0.x. É um projeto novo e muda rápido. Leia o changelog antes de atualizar, especialmente se você tem scripts usando a API.
Conclusão
O Herdr não deixa nenhum agente mais inteligente. O que ele muda é o ambiente em volta deles:
- Os agentes sobrevivem a você fechar o terminal ou perder a conexão.
- Você sabe quem precisa de você sem olhar terminal por terminal.
- Worktree, pane e agente viram um comando só, em vez de três terminais e um
cd. - Tudo é scriptável, inclusive por outro agente.
- Várias máquinas aparecem numa janela só.
Se você roda um agente por vez, provavelmente não precisa dele. Se você já se pegou com três ou quatro agentes abertos e perdendo o controle de quem está fazendo o quê, vale muito testar.