TUI (interface de terminal)

A TUI é o front-end moderno do Hermes — uma interface de terminal apoiada no mesmo runtime Python da CLI clássica. Mesmo agente, mesmas sessões, mesmos comandos de barra; uma superfície mais limpa e mais responsiva para interagir com tudo isso.

É o jeito recomendado de rodar o Hermes de forma interativa.

Como abrir

# Abrir a TUI
hermes --tui

# Retomar a sessão de TUI mais recente (cai para a sessão clássica mais recente)
hermes --tui -c
hermes --tui --continue
hermes --tui --resume latest

# Retomar uma sessão específica por ID ou título
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "minha s3ssão top"

# Retomar a sessão mais recente de um diretório de projeto específico
hermes --tui --resume latest --in ./meu-projeto

# Rodar direto do código-fonte — pula o passo de pré-compilação (para quem contribui com a TUI)
hermes --tui --dev

Você também pode ligar por variável de ambiente:

export HERMES_TUI=1
hermes          # agora usa a TUI
hermes chat     # idem

Ou tornar isso o padrão permanente em ~/.hermes/config.yaml:

display:
  interface: tui   # "cli" (padrão) ou "tui"

Com display.interface: tui, um hermes sem argumentos (e o hermes chat) abre a TUI. Flags explícitas sempre vencem — rode hermes --cli para voltar ao REPL clássico em uma única invocação, ou hermes --tui / HERMES_TUI=1 para forçar a TUI quando o padrão da configuração é cli.

A CLI clássica continua sendo o padrão de fábrica. Tudo que está documentado em Interface de linha de comando — comandos de barra, comandos rápidos, pré-carregamento de skills, personalidades, entrada em várias linhas, interrupções — funciona igual na TUI.

Por que a TUI

• Primeiro quadro instantâneo — o banner é pintado antes de o app terminar de carregar, então o terminal nunca parece travado enquanto o Hermes está subindo.
• Entrada que não trava — digite e enfileire mensagens antes de a sessão estar pronta. Seu primeiro prompt é enviado no instante em que o agente fica online.
• Sobreposições ricas — seletor de modelo, seletor de sessão, pedidos de aprovação e de esclarecimento aparecem como painéis modais, e não como fluxos embutidos na conversa.
• Painel de sessão ao vivo — ferramentas e skills vão sendo preenchidas conforme inicializam.
• Seleção amigável ao mouse — arraste para destacar com um fundo uniforme, em vez do inverso SGR. Copie com o gesto normal de cópia do seu terminal.
• Renderização em tela alternativa — atualizações diferenciais significam sem tremeliques no streaming e sem sujeira no histórico de rolagem depois que você sai.
• Recursos do compositor — recolhimento de colagens longas em linha, colagem de texto com Cmd+V / Ctrl+V com fallback para imagem da área de transferência, segurança de colagem entre colchetes e normalização de anexos por caminho de imagem ou arquivo.

Valem os mesmos skins e personalidades. Troque no meio da sessão com /skin ares, /personality pirate, e a interface se repinta ao vivo. Veja Skins e temas para a lista completa de chaves personalizáveis e quais delas valem para a clássica e para a TUI — a TUI respeita a paleta do banner, as cores da interface, o glifo e a cor do prompt, a exibição de sessão, o menu de completar, o fundo de seleção, o tool_prefix e o help_header.

Seções recolhíveis do banner

O banner de abertura da TUI agrupa as informações de runtime em quatro seções recolhíveis, cada uma com uma seta ▸ / ▾ ao lado do título:

Seção	Estado padrão
Tools	Aberta
Skills	Recolhida
System Prompt	Recolhida
MCP Servers	Recolhida

Clique em qualquer ponto do cabeçalho da seção (ou na seta) para alternar. A lista de Tools abre por padrão porque é a seção mais consultada no começo da sessão; Skills, System Prompt e MCP Servers ficam recolhidas por padrão para o banner continuar compacto mesmo quando você instalou dezenas de skills ou ligou vários servidores MCP. O estado é local à instância do banner, então a próxima abertura volta aos padrões.

Requisitos

• Node.js ≥ 20 — a TUI roda como um subprocesso lançado pela CLI em Python. O hermes doctor verifica isso.
• TTY — assim como na CLI clássica, redirecionar a entrada padrão ou rodar em ambientes não interativos cai no modo de consulta única.

Na primeira abertura, o Hermes instala as dependências Node da TUI em ui-tui/node_modules (uma vez só, alguns segundos). As aberturas seguintes são rápidas. Se você atualizar o Hermes, o pacote da TUI é recompilado automaticamente quando os fontes ficam mais novos que o dist.

Trabalhando com várias worktrees do git?

Quem contribui e roda hermes --tui --dev de muitas worktrees pode compartilhar um único node_modules em vez de instalar por checkout — veja TUI e desktop em worktrees.

Pré-compilação externa

Distribuições que já trazem um pacote pré-compilado (Nix, pacotes do sistema) podem apontar o Hermes para ele:

export HERMES_TUI_DIR=/caminho/do/prebuilt/ui-tui
hermes --tui

O diretório precisa conter dist/entry.js.

Atalhos de teclado

Os atalhos são exatamente os da CLI clássica. As únicas diferenças de comportamento:

• Arrastar com o mouse destaca o texto com um fundo de seleção uniforme.
• Cmd+V / Ctrl+V tenta primeiro a colagem normal de texto, depois cai para leituras de área de transferência por OSC52 ou nativas, e por fim anexa uma imagem quando a área de transferência ou o conteúdo colado resolve para uma imagem.
• /terminal-setup instala atalhos locais de terminal do VS Code / Cursor / Windsurf, para melhor paridade de Cmd+Enter e de desfazer/refazer no macOS.
• Autocompletar de barra abre como painel flutuante com descrições, e não como uma lista embutida.
• Ctrl+X abre o alternador de sessões ao vivo. Quando uma mensagem enfileirada está destacada (enviada enquanto o agente ainda rodava), ele continua apagando essa mensagem enfileirada. Esc cancela a edição e tira o destaque sem apagar.
• Ctrl+G / Ctrl+X Ctrl+E — abrem o buffer de entrada atual no $EDITOR, para compor prompts longos ou de várias linhas; salvar e sair envia o conteúdo de volta como prompt.

Comandos de barra

Todos os comandos de barra funcionam sem mudança. Alguns são próprios da TUI — produzem saída mais rica ou aparecem como sobreposições em vez de painéis embutidos:

Comando	Comportamento na TUI
/help	Sobreposição com os comandos categorizados, navegável pelas setas
/sessions (apelido /switch)	Alternador de sessões ao vivo — lista as sessões de TUI abertas, alterna entre elas, fecha ou começa outra
/model	Seletor de modelo modal, agrupado por provedor, com dicas de custo
/skin	Prévia ao vivo — a mudança de tema é aplicada enquanto você navega
/details	Alterna os detalhes verbosos de chamada de ferramenta (global ou por seção)
/usage	Painel rico de tokens, custo e contexto
/agents (apelido /tasks)	Sobreposição de observabilidade — árvore de subagentes ao vivo com controles de encerrar e pausar, somatórios de custo, tokens e arquivos por ramo, histórico turno a turno
/reload	Relê o ~/.hermes/.env no processo da TUI em execução, para novas chaves de API valerem sem reiniciar
/mouse [on|off|toggle|wheel|buttons|all]	Escolhe um preset de rastreamento de mouse em tempo de execução (também persiste em display.mouse_tracking no config.yaml). wheel (1000+1006) mantém a rolagem pela rodinha sem os eventos de passagem do mouse que fazem o tmux encher a linha do prompt de "No image in clipboard"; buttons adiciona a seleção por arrasto; all é o padrão, com interface reativa à passagem do mouse.

Todos os outros comandos de barra (incluindo skills instaladas, comandos rápidos e alternâncias de personalidade) funcionam igual à CLI clássica. Veja a referência de comandos de barra.

Alternador de sessões ao vivo

Use o alternador de sessões ao vivo quando quiser que um terminal atue como despachante de várias sessões de TUI. Ele lista apenas as sessões que estão vivas neste processo da TUI; sessões fechadas continuam salvas como transcrições e ainda podem ser reabertas com /resume ou hermes --tui --resume <id-ou-titulo>.

Abra de qualquer um destes jeitos:

• Ctrl+X dentro da TUI.
• /sessions ou /switch.
• /sessions new para criar uma sessão viva na hora.
• Clicando na contagem N live sessions na linha de status.

Dentro do alternador:

• ↑ / ↓ movem a seleção; cliques de mouse também selecionam linhas.
• Enter alterna para a sessão viva selecionada.
• Ctrl+D fecha a sessão viva selecionada.
• Ctrl+N começa uma sessão viva em branco.
• Ctrl+R atualiza a lista de sessões vivas.
• Esc fecha o alternador.
• Selecione +new, digite um prompt e aperte Enter para despachar uma sessão viva nova. Aperte Tab antes se quiser escolher um modelo só para essa sessão nova.

Renderização de matemática em LaTeX

O pipeline de markdown da TUI renderiza matemática em LaTeX na linha: $E = mc^2$ e $$\frac{a}{b}$$ aparecem como matemática formatada em Unicode, e não como o TeX cru. Funciona para matemática em linha e em bloco; sintaxe não suportada cai para mostrar o TeX literal dentro de um trecho de código, para continuar copiável.

Isso é sempre ligado — não há nada a configurar. A CLI clássica mantém o TeX cru.

Detecção de terminal claro

A TUI detecta terminais claros automaticamente e troca para o tema claro. A detecção funciona em três camadas:

1. Variável de ambiente HERMES_TUI_THEME — a de maior prioridade. Valores: light, dark ou um hexadecimal cru de 6 caracteres para o fundo (por exemplo ffffff, 1a1a2e).
2. Variável de ambiente COLORFGBG — a dica clássica de "qual é a minha cor de fundo?", usada pelos terminais derivados do xterm.
3. Sondagem do fundo do terminal por OSC 11 — funciona em terminais modernos (Ghostty, Warp, iTerm2, WezTerm, Kitty) que não definem COLORFGBG.

Se você quer o tema claro para sempre, independentemente do terminal:

export HERMES_TUI_THEME=light

Estilos do indicador de ocupado

O indicador de ocupado da barra de status é plugável — o padrão gira a paleta de rostinhos kawaii do Hermes a cada 2,5 segundos enquanto o agente trabalha. Escolha outro estilo pela configuração ou pelo comando de barra /indicator:

display:
  tui_status_indicator: kaomoji   # kaomoji | emoji | unicode | ascii

Ou dentro da sessão: /indicator emoji (e assim por diante). Os estilos vêm com larguras de glifo casadas, para o resto da barra de status não tremer na rotação.

Retomada automática

Por padrão, o hermes --tui começa uma sessão nova a cada abertura. Para reconectar automaticamente à sessão de TUI mais recente (útil quando o terminal ou a conexão SSH cai de repente), habilite:

export HERMES_TUI_RESUME=1          # sessão de TUI mais recente
# ou:
export HERMES_TUI_RESUME=<id-da-sessao>   # sessão específica

Remova a variável ou passe --resume <id> explicitamente para sobrescrever em uma abertura específica.

Linha de status

A linha de status da TUI acompanha o estado do agente em tempo real:

Depois que a sessão ganha um nome, o título aparece como um selo colorido na ponta direita da linha de status. O título toma o lugar do rótulo do espaço de trabalho e é cortado em terminais estreitos.

Status	Significado
starting agent…	O ID da sessão já existe; ferramentas e skills ainda estão subindo. Você pode digitar — as mensagens ficam na fila e são enviadas quando dá.
ready	O agente está ocioso, aceitando entrada.
thinking… / running…	O agente está raciocinando ou rodando uma ferramenta.
interrupted	O turno atual foi cancelado; aperte Enter para enviar de novo.
forging session… / resuming…	Conexão inicial ou aperto de mão do --resume.

As cores e os limiares da barra de status por skin são compartilhados com a CLI clássica — veja Skins para personalizar.

A linha de status também mostra:

• Diretório de trabalho com o ramo do git — ~/projetos/hermes-agent (docs/two-week-gap-sweep). O sufixo do ramo é atualizado quando você faz git checkout em outro terminal (com cache por mtime), então a TUI reflete o ramo realmente ativo, e não o que estava ativo na abertura.
• Tempo decorrido por prompt — ⏱ 12s/3m 45s enquanto o turno roda (ao vivo), congelado em ⏲ 32s / 3m 45s quando o turno termina. O primeiro número é o tempo desde a última mensagem sua; o segundo é a duração total da sessão. Zera a cada prompt novo.
• 🗜️ N — quantas vezes a sessão em execução foi comprimida automaticamente. Aparece assim que a primeira compressão dispara.
• ▶ N — quantas tarefas de /background estão rodando nesta sessão. Aparece sempre que há pelo menos uma tarefa em andamento.
• ⚠ YOLO — aviso visível sempre que o modo YOLO está ligado (hermes --yolo, /yolo ou HERMES_YOLO_MODE=1). O mesmo selo também aparece no banner de abertura, então você não consegue abrir uma sessão que aprova tudo automaticamente sem perceber.

Configuração

A TUI respeita toda a configuração padrão do Hermes: ~/.hermes/config.yaml, perfis, personalidades, skins, comandos rápidos, pools de credenciais, provedores de memória, habilitação de ferramentas e skills. Não existe arquivo de configuração específico da TUI.

Um punhado de chaves ajusta especificamente a superfície da TUI:

display:
  skin: default              # qualquer skin embutido ou próprio
  personality: helpful
  details_mode: collapsed    # hidden | collapsed | expanded — padrão global do acordeão
  sections:                  # opcional: sobrescritas por seção (qualquer subconjunto)
    thinking: expanded       # sempre aberta
    tools: expanded          # sempre aberta
    activity: collapsed      # volta a ATIVAR o painel de atividade (escondido por padrão)
  mouse_tracking: all        # off | wheel | buttons | all (ou true/false por compatibilidade).
                             #   wheel   — 1000+1006 (rolagem + clique; sem arrasto, sem passagem —
                             #             recomendado dentro do tmux para calar o spam de
                             #             "No image in clipboard" na linha do prompt vindo dos
                             #             eventos de passagem do mouse)
                             #   buttons — acrescenta 1002 para seleção por arrasto no terminal
                             #   all     — acrescenta 1003 para passagem do mouse (paginar a barra de
                             #             rolagem ao passar, mouseenter em links etc.)

Alternâncias em tempo de execução:

• /details [hidden|collapsed|expanded|cycle] — define o modo global
• /details <seção> [hidden|collapsed|expanded|reset] — sobrescreve uma seção (seções: thinking, tools, subagents, activity)

Visibilidade padrão

A TUI vem com padrões opinativos por seção, que transmitem o turno como uma transcrição ao vivo em vez de uma parede de setinhas:

• thinking — expanded. O raciocínio é transmitido na linha conforme o modelo o emite.
• tools — expanded. As chamadas de ferramenta e os resultados delas aparecem abertos.
• subagents — cai no details_mode global (recolhido sob a setinha por padrão — fica quieto até uma delegação de fato acontecer).
• activity — hidden. O meta ambiente (dicas de gateway, cutucadas de paridade com o terminal, notificações de segundo plano) é ruído para a maior parte do uso do dia a dia. Falhas de ferramenta continuam aparecendo na linha da ferramenta que falhou; erros e avisos ambientes aparecem por um alerta flutuante de contingência quando todos os painéis estão escondidos.

As sobrescritas por seção têm precedência tanto sobre o padrão da seção quanto sobre o details_mode global. Para remodelar o layout:

• display.sections.thinking: collapsed — põe o raciocínio de volta sob uma setinha
• display.sections.tools: collapsed — põe as chamadas de ferramenta de volta sob uma setinha
• display.sections.activity: collapsed — traz o painel de atividade de volta
• /details <seção> <modo> em tempo de execução

Qualquer coisa definida explicitamente em display.sections vence os padrões, então configurações já existentes continuam funcionando sem mudança.

Sessões

As sessões são compartilhadas entre a TUI e a CLI clássica — as duas escrevem no mesmo ~/.hermes/state.db. Você pode começar uma sessão em uma e retomar na outra. O seletor de sessões mostra as sessões das duas origens, com uma etiqueta de origem.

Veja Sessões para ciclo de vida, busca, compressão e exportação.

Como a TUI conversa com o gateway dela

Por padrão, a TUI sobe o próprio gateway no processo, então cada instância de TUI é autossuficiente — não há nada a configurar.

Você pode ver uma variável de ambiente HERMES_TUI_GATEWAY_URL citada no código ou nos logs. Isso é um detalhe interno de ligação do painel web, não uma opção de anexar a uma instância remota. Quando você abre a aba "Chat" do painel (hermes dashboard → /chat), o servidor web do painel sobe um processo filho de TUI embutido e injeta HERMES_TUI_GATEWAY_URL para esse filho se conectar ao tui_gateway do próprio painel, no mesmo processo, por um WebSocket de loopback (/api/ws). O endpoint /api/ws só existe dentro do servidor do painel (hermes_cli/web_server.py) e está atrelado ao tempo de vida e à autenticação daquele processo.

Não existe um modo geral de "apontar qualquer TUI para qualquer porta de gateway isolada". Em particular, o servidor de API compatível com a OpenAI (hermes gateway / a plataforma api_server) não serve /api/ws — ele é a superfície de backend de modelo (/v1/chat/completions, /v1/models, …) e deliberadamente não expõe o canal de controle JSON-RPC da TUI. Apontar HERMES_TUI_GATEWAY_URL para essa porta vai dar 404.

Se você quer que várias superfícies compartilhem um mesmo conjunto de sessões, use o ~/.hermes/state.db compartilhado (veja Sessões) ou o chat embutido do painel web (veja Painel web) — e não uma URL de gateway definida na mão.

Voltar para a CLI clássica

Abrir hermes (sem --tui) continua na CLI clássica por padrão. Para uma máquina preferir a TUI, defina display.interface: tui em ~/.hermes/config.yaml (permanente) ou HERMES_TUI=1 no perfil do seu shell (por shell). Para voltar, defina interface: cli / remova a variável de ambiente, ou passe hermes --cli para uma vez só.

Se a TUI não conseguir abrir (sem Node, pacote faltando, problema de TTY), o Hermes imprime um diagnóstico e cai para a clássica — em vez de deixar você travado.

Veja também

• Interface de linha de comando — referência completa de comandos de barra e atalhos (compartilhada)
• Sessões — retomar, ramificar e histórico
• Skins e temas — dê tema ao banner, à barra de status e às sobreposições
• Modo de voz — funciona nas duas interfaces
• Configuração — todas as chaves de configuração

---