Pets (Mascotes Petdex)

O Hermes pode exibir um pet animado — um pequeno sprite de mascote que reage ao que o agente está fazendo (parado, rodando uma ferramenta, pensando, terminando, falhando) na CLI, na TUI e no aplicativo desktop. Os pets vêm da galeria pública petdex.

Pets são puramente cosméticos. Eles não têm efeito nenhum sobre cache de prompt, tokens ou o comportamento do agente — o sprite é só uma questão de exibição. O recurso vem desligado por padrão e fica dormente até você instalar e selecionar um pet.

Como funciona

• Os pets são instalados no diretório pets/ do seu perfil (<HERMES_HOME>/pets/<slug>/), então cada perfil mantém o próprio conjunto.

• Selecionar um pet grava display.pet.slug e display.pet.enabled no config.yaml — nada é guardado como segredo nem como variável de ambiente.

• Cada superfície observa a atividade que já acompanha e mapeia para um de seis estados de animação. O mapeamento fica num lugar só, para que todas as superfícies se comportem igual:

  Atividade do agente	Estado do pet
  Uma ferramenta/turno acabou de falhar	failed
  Um plano terminou (todos os todos concluídos)	jump (comemorar)
  Um turno terminou sem erro	wave
  Uma ferramenta está executando	run
  O modelo está pensando/lendo	review
  Turno em andamento (indefinido)	run
  Esperando por você (há um pedido de esclarecimento ou aprovação aberto)	waiting (cai para idle em folhas antigas de 8 linhas)
  Nada acontecendo	idle

Renderização

No terminal (CLI/TUI), o Hermes renderiza o sprite em fidelidade total quando o seu terminal suporta um protocolo gráfico (kitty, Ghostty, WezTerm, iTerm2 ou sixel). Caso contrário, ele cai automaticamente para uma renderização Unicode em meio-bloco com cor verdadeira. Dentro de um pipe ou redirecionamento (sem TTY), a renderização no terminal é desligada de propósito.

O aplicativo desktop desenha o pet como um sprite flutuante em um canvas e liga/desliga em Settings → Appearance.

Início rápido (CLI)

# Navegue pela galeria (filtre por trecho de texto)
hermes pets list
hermes pets list cat

# Instale um pet e deixe ele ativo em um passo só
hermes pets install boba --select

# Veja / anime ele no seu terminal (Ctrl+C para parar)
hermes pets show

# Confira a sua configuração
hermes pets doctor

Comandos hermes pets

Objetivo	Comando
Navegar pela galeria	hermes pets list [query] [--limit N]
Listar os pets instalados	hermes pets list --installed
Instalar um pet	hermes pets install <slug> [--select] [--force]
Definir o pet ativo	hermes pets select [slug] (omita o slug para abrir um seletor)
Redimensionar o pet em todo lugar	hermes pets scale <factor> (por exemplo 0.5, limitado a 0.1–3.0)
Visualizar/animar	hermes pets show [slug] [--state <s>] [--cycle] [--once] [--mode <m>] [--scale <f>]
Desligar o pet	hermes pets off
Remover um pet instalado	hermes pets remove <slug>
Diagnosticar a configuração	hermes pets doctor

Opções de hermes pets show:

• --state — toca um único estado (idle, wave, run, failed, review, jump).
• --cycle — passa por todos os estados.
• --once — toca uma vez em vez de ficar em loop.
• --mode — força o protocolo de renderização (kitty, iterm, sixel, unicode, auto).
• --scale — força a escala na tela (0 = usar a configuração).

Comando de barra /pet

Na CLI e na TUI você gerencia o pet sem sair da sessão:

• /pet — liga/desliga o pet (adota o primeiro pet instalado, se nenhum estiver ativo).
• /pet list — navega pela galeria.
• /pet scale <factor> — redimensiona o pet em todo lugar (por exemplo /pet scale 0.5).
• /pet <slug> — adota um pet específico.
• /pet off — desliga o pet.

Na TUI, /pet list abre um seletor interativo em sobreposição; no aplicativo desktop, abre a paleta de pets do Cmd+K.

Gerar um pet (/hatch)

Além de instalar pets prontos da galeria, o Hermes consegue gerar um pet inédito a partir de uma descrição em texto — com um pipeline próprio de geração de sprites por IA.

• CLI/TUI: /hatch <descrição> (apelido /generate-pet), ou hermes pets → o fluxo de geração.
• Aplicativo desktop: a interface de generate no estilo Pokédex — um ovo animado, efeitos de choco e um seletor de rascunhos.

Como a geração funciona (um fluxo de dois passos, com custo limitado):

1. Rascunhos base — um punhado de variantes baratas, só de prompt, de "com que cara este pet deveria ficar". Você escolhe uma, ou remixa/tenta de novo para uma rodada nova.
2. Choco — a base escolhida vira imagem de referência para gerar uma linha de animação embasada por estado do Hermes (parado, pensando, usando ferramenta, etc.), que são fatiadas em quadros de forma determinística e empacotadas em um atlas petdex/Codex padrão (grade 8×9 de células de 192×208). O resultado é um spritesheet válido que fica com você — e que poderia ir para o petdex submit.

Backend de imagem

A geração usa o provedor de geração de imagem ativo, mas exige embasamento por imagem de referência, para que cada linha de animação continue sendo o mesmo personagem da base. Backends com suporte a referência: Nous Portal, OpenRouter, OpenAI (gpt-image-2) e Krea. OpenRouter/Nous rodam por padrão uma cadeia de modelos com qualidade em primeiro lugar.

• A ordem de resolução prefere Nous Portal → OpenAI → OpenRouter.
• Se nenhum backend com suporte a referência estiver configurado, a geração mostra um erro acionável apontando para hermes tools → Image Generation. (Instalar/adotar pets já existentes da galeria não precisa de backend de imagem.)
• Force o backend com a variável de ambiente HERMES_PET_IMAGE_PROVIDER (por exemplo, HERMES_PET_IMAGE_PROVIDER=openrouter).

Aplicativo desktop

No aplicativo desktop você gerencia o pet de duas formas:

• Cmd+K → "Pets…" — navegue, busque, adote e ligue/desligue pets sem tirar as mãos do teclado (espelha o seletor de temas).
• Settings → Appearance — a mesma galeria mais um controle deslizante de tamanho que redimensiona o mascote flutuante ao vivo, enquanto você arrasta.

Os dois adotam/ligam/redimensionam o mascote flutuante no lugar — mudanças de tamanho valem na hora; adotar um pet novo acende ele em um instante.

Passeio

Em Settings → Appearance existe um botão Roam: quando ligado, o pet perambula pela janela por conta própria enquanto o agente está parado — andando pelas superfícies, fazendo pausas e pulando entre pontos. O passeio só acontece enquanto o pet está dentro da janela, ativo e o agente em repouso; qualquer estado vindo do agente (trabalhando, comemorando) assume na hora. O botão vem desligado por padrão e é preservado entre reinícios.

Redimensionar com Alt+roda

Segure Alt e gire a roda do mouse sobre o pet para redimensionar ele no lugar — tanto na janela do aplicativo quanto na sobreposição destacada. A sobreposição amplia na direção do cursor e a escala resultante é preservada, então ela sobrevive a reinícios e fica em sincronia com o pet dentro do aplicativo.

Reações de carinho

Diga algo gentil ao agente — "good bot", "thank you", "ily", <3 ou um emoji de coração — e o pet reage com corações flutuantes (desktop) ou um flash de coração (CLI/TUI). A detecção é um léxico curado, sem gasto de token, comparado localmente em cada mensagem do usuário (sem chamada de modelo); ela dispara com afeto e gratidão dirigidos ao agente, não com sentimento positivo em geral. Todas as superfícies — pet da CLI, TUI, pet flutuante do desktop e a sobreposição destacada — reagem ao mesmo sinal.

Sobreposição destacada

Shift+clique no pet flutuante para destacar ele em uma janela própria, transparente e sempre por cima. Lá fora ele continua visível com o Hermes minimizado (no estilo do Codex), então uma olhada já diz o que o agente está fazendo.

Gestos depois de destacado:

Gesto	Ação
Arrastar	Move o pet para qualquer lugar da tela, inclusive fora do aplicativo. A posição e o estado dentro/fora são preservados entre reinícios.
Clique simples	Abre um mini compositor para mandar um prompt para a sessão mais recente — sem trazer o aplicativo para a frente.
Clique duplo	Alterna a janela do aplicativo: minimiza se ela está na frente, restaura se está escondida.
Shift+clique	Devolve o pet para dentro da janela.
Ícone de correio	Aparece só quando um turno terminou enquanto você estava longe; clique para trazer o aplicativo na conversa mais recente (e marcar como lida).

Só o pet destacado mostra um balão de fala (working…, thinking…, your turn, …) — dentro da janela quem faz esse papel é o próprio aplicativo, então ali o pet fica quieto.

A sobreposição é um fantoche puro do pet do aplicativo — não carrega conexão separada com o gateway e nunca aparece na dock nem no alternador de aplicativos.

Configuração

Todas as opções ficam sob display.pet no config.yaml:

display:
  pet:
    enabled: false        # liga/desliga geral (true assim que você seleciona um pet)
    slug: ""              # pet ativo; vazio = o primeiro instalado
    render_mode: auto      # auto | kitty | iterm | sixel | unicode | off
    scale: 0.33           # controle-mestre de tamanho (relativo aos quadros nativos de 192x208)
    unicode_cols: 0       # força a largura no terminal (0 = derivar da escala)

• scale é o único controle-mestre de tamanho. Um número encolhe todas as superfícies: o canvas do desktop escala os pixels por ele, e a CLI/TUI derivam dele a largura em colunas do terminal. O fallback em meio-bloco tem um piso de legibilidade — ele não consegue encolher tanto quanto a renderização em pixel real do kitty/GUI sem virar borrão, então a mesma scale fica nítida no kitty mas trava no piso em meio-blocos.
• render_mode: auto detecta kitty/iTerm2/sixel e cai para meio-blocos unicode. Defina explicitamente para forçar um protocolo, ou off para desligar a renderização no terminal mantendo o pet no desktop.
• unicode_cols fixa a largura em colunas do terminal independentemente de scale; deixe em 0 para derivar a largura de scale.

Solução de problemas

Rode hermes pets doctor — ele informa:

• o diretório de pets e quais pets estão instalados,
• display.pet.enabled, display.pet.slug e o pet ativo resolvido,
• o render_mode configurado, o protocolo gráfico detectado no terminal e o modo efetivo para um TTY,
• se o Pillow (usado para decodificar sprites) pode ser importado.

Ele imprime ✓ ready assim que um pet está instalado, selecionado, habilitado e o Pillow está disponível.

Pegadinhas comuns:

• Um pet só aparece depois que ele está instalado E selecionado (enabled: true).
• Dentro de um pipe/redirecionamento (sem TTY), a renderização no terminal é desligada de propósito.
• A CLI npm do petdex instala em ~/.codex/pets; o Hermes usa o próprio <HERMES_HOME>/pets/, com escopo de perfil — instale pelo hermes pets.

Veja também

• A skill hermes-agent deixa o agente instalar e trocar pets para você quando pedir (veja o references/petdex.md dela).

---