Ir para o conteúdo
Promovaweb

Atalhos, temas e barra lateral do Herdr

O Herdr TUI lê as preferências de um único arquivo TOML, o config.toml, que fica em ~/.config/herdr/ no Linux. Todas as chaves são opcionais e começam comentadas no arquivo padrão. O comando herdr --default-config imprime esse arquivo completo, e herdr server reload-config aplica uma alteração no servidor em execução.

Um arquivo para todas as preferências

O caminho do arquivo aparece na própria ajuda do comando: herdr --help mostra a linha Config com o local do config.toml na máquina, ao lado dos arquivos de log. A variável HERDR_CONFIG_PATH troca esse caminho, recurso útil para testar uma configuração sem alterar a principal. As sessões nomeadas compartilham o mesmo arquivo.

O arquivo padrão impresso por herdr --default-config traz todas as seções com os valores de fábrica comentados. Você copia a chave que quer mudar, tira o comentário e altera o valor. Depois de editar, o atalho prefix+shift+r ou o comando herdr server reload-config recarrega o arquivo no servidor em execução, sem fechar os painéis. Quando os atalhos personalizados criam conflito, herdr config reset-keys guarda uma cópia do arquivo e remove as teclas personalizadas.

As seções principais do arquivo e o que cada uma controla:

  • [keys]O prefixo, os atalhos de cada ação e os comandos próprios.
  • [theme]O tema embutido, a troca entre claro e escuro e as cores personalizadas.
  • [ui]A barra lateral, as bordas dos painéis, o mouse e a barra de abas.
  • [ui.toast] e [ui.sound]Os avisos e os sons quando um agente muda de estado.
  • [session]A retomada das conversas dos agentes depois de um reinício.
  • [worktrees] e [remote]A pasta dos worktrees e o SSH gerenciado pelo Herdr.

O prefixo e os atalhos

Os atalhos do Herdr usam um prefixo, ctrl+b por padrão, seguido da tecla da ação. A chave prefix, na seção [keys], troca essa combinação. Cada ação tem a própria chave, como split_vertical = "prefix+v", close_pane = "prefix+x", zoom = "prefix+z" e toggle_sidebar = "prefix+b". Algumas ações vêm sem atalho, como a troca direta para o próximo agente. Essas ações recebem uma tecla quando você preenche a chave correspondente.

Os saltos indexados dispensam o prefixo para números. Na seção [keys.indexed], o valor tabs = "ctrl" faz ctrl+1 a ctrl+9 trocarem de aba direto. Com agents = "alt", as teclas alt+1 a alt+9 focam as linhas de agente da barra lateral. A lista dos atalhos padrão, com o modo e a ação de cada um, está em Atalhos do Herdr TUI.

Os comandos próprios ficam em blocos [[keys.command]], cada um com a tecla, o tipo e o comando. O tipo define como o comando aparece na tela. Eles rodam na máquina do servidor, detalhe que importa no uso remoto, como mostra a última seção.

Tipo de comando próprioO que aconteceExemplo de uso
type = "shell"Roda o comando em segundo plano, sem abrir painel.Um script que grava uma anotação ou dispara uma notificação.
type = "pane"Abre um painel temporário, que fecha quando o comando termina.Um teste rápido que você quer ver rodando e sumir no fim.
type = "popup"Abre um terminal sobreposto, sem mudar o layout da aba.O exemplo do arquivo padrão: lazygit em prefix+alt+g, com 80% da largura e da altura.

Tema, cores e indicadores

O tema padrão é o Catppuccin. A chave name, na seção [theme], escolhe outro tema embutido. Com auto_switch = true, o Herdr alterna entre o tema escuro de dark_name e o claro de light_name, acompanhando o modo do terminal. As subseções de cores personalizadas substituem cores específicas do tema, como o fundo da barra lateral, a cor de seleção e o acento, com valores em hexadecimal.

A seção [ui] também define a cor de acento das bordas e da navegação, em hexadecimal, por nome ou em rgb(). A chave status_indicators troca os pontos coloridos que marcam o estado dos agentes por símbolos distintos para cada estado, alternativa útil quando a diferença de cor não basta para distinguir blocked de working.

Barra lateral e interface

A barra lateral começa com 26 colunas e aceita de 18 a 36, pelas chaves sidebar_width, sidebar_min_width e sidebar_max_width. A chave sidebar_start_collapsed abre a barra recolhida. A chave mobile_width_threshold, com 64 colunas por padrão, define a largura abaixo da qual a interface usa o layout para telas estreitas, o mesmo que aparece num cliente SSH no celular.

O conteúdo de cada linha da barra também é configurável. Em [ui.sidebar.agents], a chave rows monta as linhas de cada agente com itens como o ícone de estado, a máquina, o workspace, a aba e o título do terminal. A chave rows_by_agent define linhas diferentes para um agente específico. Com agent_panel_sort = "priority", a lista de agentes vira uma fila de atenção, com os que aguardam resposta primeiro, em vez de ficar agrupada por workspace.

Entre as demais chaves da seção, mouse_capture = false desliga a captura do mouse quando você prefere trabalhar só com o teclado. A chave confirm_close controla a confirmação ao fechar, tab_bar_position coloca a barra de abas em cima ou embaixo e window_title define o título que o Herdr escreve na janela do terminal externo, com marcadores como {hostname} e {workspace}.

Avisos e sons

Os avisos ficam desligados por padrão. A chave delivery, na seção [ui.toast], aceita quatro valores: off, herdr para um aviso dentro da interface, terminal para a notificação mostrada pelo terminal externo e system para a notificação enviada direto ao serviço do sistema operacional. A chave delay_seconds define a espera até o aviso aparecer.

Os sons vêm ligados e soam quando um agente de um workspace em segundo plano muda de estado. A seção [ui.sound] aceita um arquivo MP3 próprio para todos os avisos ou arquivos separados para conclusão e para atenção necessária, com caminhos relativos à pasta do arquivo de configuração. A subseção [ui.sound.agents] liga ou desliga o som por agente. O Droid vem mudo por padrão.

Cliente e servidor no uso remoto

Algumas preferências pertencem ao cliente e outras ao servidor, diferença que aparece quando você usa o Herdr em outra máquina. No herdr --remote e nas máquinas cadastradas, a interface usa o tema, a barra lateral e os atalhos do cliente local. Os comandos próprios e os plugins rodam no servidor selecionado, porque o Herdr não copia comandos, configuração, executáveis nem segredos locais para os hosts SSH.

A seção [server] guarda preferências do próprio servidor, como o tamanho do terminal usado quando nenhum cliente está ligado. A seção [session] controla a retomada dos agentes, explicada na página Sessões e restauração. A página Configuração do Herdr reúne exemplos copiáveis das chaves mais usadas.

Configuração do Herdr

O Herdr funciona sem um arquivo de configuração pessoal. Edite esse arquivo para selecionar o shell, personalizar as teclas ou ajustar a apresentação da interface.

Localize o arquivo

No Linux e macOS, o caminho padrão documentado é ~/.config/herdr/config.toml. No Windows, ele fica em %APPDATA%\herdr\config.toml. Variáveis de ambiente e opções do ambiente de execução podem mudar o caminho resolvido.

Terminal
herdr --help
herdr --default-config

A primeira consulta informa o caminho resolvido. A segunda imprime os valores padrão, sem substituir seu arquivo. Guarde uma cópia do arquivo existente antes de editá-lo.

Escolha o shell dos novos painéis

Este exemplo seleciona /bin/sh e evita carregamento como login shell no Linux:

[terminal]
default_shell = "/bin/sh"
shell_mode = "non_login"

O valor de default_shell deve ser um executável existente. Os painéis já abertos mantêm o shell atual. Crie um painel depois da alteração para conferir o novo comportamento.

Recarregue a configuração

Terminal
herdr --session tutorial server reload-config

Esse comando foi executado na sessão isolada usada para revisar a trilha. Opções aplicadas somente na inicialização ainda exigem reinício, que encerra os processos dos painéis.

Diferencie cliente e servidor

Temas, aparência da lateral e comportamento de cópia usam a configuração local do cliente. Padrões dos painéis e integrações pertencem ao servidor que executa os processos. Ao usar uma máquina remota, confira qual arquivo você está editando antes de esperar uma mudança na interface.

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.