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.
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.
herdr --helpherdr --default-configA 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
herdr --session tutorial server reload-configEsse 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.