01Modelo mental

Hermes não é um chatbot que “sabe” coisas. É um loop: o modelo decide, as ferramentas executam, o resultado volta para o contexto, e ele decide de novo — até terminar.

Isso explica a regra mais importante do manual: tudo que é verificável é verificado na máquina. Data, versão, se o serviço está de pé, conteúdo de arquivo, soma — nada disso vem da memória do modelo. Se uma resposta depende de fato externo, o caminho é uma ferramenta.

02CLI essencial

O binário hermes sem argumento abre o chat interativo. Todo o resto é subcomando.

Todo dia

hermes                          # chat interativo
hermes chat -q "pergunta"       # uma pergunta, resposta e sai
hermes -c                       # continua a sessão mais recente
hermes -c <id>                  # retoma sessão específica
hermes -p omega chat -q "..."   # roda em outro profile
hermes doctor                   # checagem de saúde geral
hermes status --all             # estado de todos os componentes

Configuração — sempre por comando, nunca editando o YAML na mão

hermes config get model.default
hermes config set display.skin synthwave
hermes config show              # dump completo
hermes config check             # valida o arquivo
hermes config edit              # abre no $EDITOR

Skills e ferramentas

hermes skills list              # instaladas
hermes skills browse            # catálogo
hermes skills search docker
hermes skills install ID        # id do hub ou URL de SKILL.md
hermes tools list               # toolsets e estado
hermes tools enable video
hermes bundles                  # pacotes de skills

Serviço, logs, sessões

hermes gateway status
hermes gateway restart
hermes logs -f                  # acompanha ao vivo
hermes logs errors              # só erros
hermes sessions list
hermes sessions browse
hermes sessions export out.md
hermes sessions prune --older 30d

Agendamento e profiles

hermes cron list
hermes cron create "every day 9am" --prompt "..."   # via CLI
hermes cron pause f1cda980daab
hermes cron run f1cda980daab
hermes profile list
hermes profile show code-gates
hermes profile create meunome --clone --description "escopo"

Flags que salvam o dia

03Comandos na conversa

Funcionam no chat, no Telegram e no TUI. /help sempre mostra a lista real — o registro muda com frequência.

Controle de sessão

Durante uma tarefa longa

Configuração em tempo real

04Como pedir bem

Esta é a seção que muda o resultado mais do que qualquer comando. O agente faz exatamente o que é verificável — então dê a ele algo verificável.

A anatomia de um bom pedido

1. RESULTADO  → o que deve existir no fim (arquivo, URL, serviço de pé)
2. CONTEXTO   → caminhos absolutos, comando exato, erro cru
3. CRITÉRIO   → como saber que funcionou (teste, curl, systemctl)
4. LIMITES    → o que NÃO tocar

Compare:

Sete padrões que funcionam sempre

05Skills

Uma skill é um SKILL.md com frontmatter e um procedimento. O sistema mostra ao modelo apenas nome + descrição (~uma linha); o corpo inteiro só entra no contexto quando a tarefa combina. É por isso que ter 100 skills não custa 100 prompts.

O que merece virar skill

# criar a partir do que acabou de funcionar
/learn esta conversa
hermes skills install https://exemplo/SKILL.md
hermes skills check            # valida frontmatter
hermes skills update

# manutenção automática (só mexe em skills criadas pelo agente)
hermes curator status
hermes curator pin minha-skill   # nunca arquivar

A descrição é o que decide se a skill carrega. Ela começa com o gatilho: “Use quando <situação>. <comportamento em uma linha>.” Descrição genérica = skill que nunca aparece.

06Memória

Três camadas diferentes, com propósitos diferentes:

Regra de alocação

• Fato estável sobre você / ambiente → memória
• Procedimento repetível → skill
• Detalhe de um projeto específico → arquivo do projeto (AGENTS.md ou doc)
• Estado de agora → nada, vive na sessão

/memory                  # revisa escritas pendentes
hermes memory status
hermes memory setup
hermes config get memory.enabled

Contexto de projeto

Um AGENTS.md (ou .hermes.md) no diretório é carregado automaticamente quando o agente trabalha ali. É o lugar certo para “como este repo funciona”, “não use Y”, “testes rodam com Z”. Escopo local, sem poluir a memória global.

07Profiles

Profile = uma instância independente: config, .env, skills, sessões e memória próprios. Serve para separar domínios — não para separar assuntos.

Sua máquina hoje:

hermes profile list
hermes profile create meu-escopo --clone --description "o que ele faz e o que recusa"
hermes profile show meu-escopo
hermes -p meu-escopo config set model.default deepseek-v4-pro
hermes -p meu-escopo chat -q "qual seu escopo?"   # valide de verdade

O que faz um profile funcionar

• SOUL.md próprio — escopo dentro, escopo fora, regras de trabalho. Sem isso ele vira uma cópia do chat principal e a separação não compra nada.
• Modelo re-escolhido — o clone herda o modelo do pai, que quase nunca é o certo para o novo papel.
• Honcho configurado — o host do profile precisa existir no honcho.json dele, não só no global.
• Bot próprio — token separado no .env do profile. Dois gateways no mesmo token colidem.

08Cron & delegação

Duas formas de trabalho fora do turno. A diferença é a durabilidade.

Cron — durável

Vive no banco, sobrevive a restart, entrega em qualquer plataforma. É o que você quer para rotina.

# via conversa: "todo dia às 8:50 me manda o check-in"
hermes cron list
hermes cron pause <id>
hermes cron run <id>        # testa agora, sem esperar o horário
hermes cron remove <id>

• Agendas: 30m, every 2h, 0 9 * * *, every monday 9am, timestamp ISO
• Knobs: skills a pré-carregar, modelo próprio, script de coleta prévia, context_from (encadeia a saída de um job no outro), workdir
• Limite: 3 minutos de execução por run. Trabalho longo vai para terminal(background=true)
• Sempre teste com cron run antes de confiar no horário

Delegação — paralela, não durável

delegate_task abre subagentes com contexto e terminal próprios. Cada um recebe só o que você passar — eles não sabem nada desta conversa.

09Telegram & gateway

O gateway (hermes-gateway.service, user unit) mantém todos os profiles conectados ao mesmo tempo. Cada DM ou thread é uma sessão separada.

hermes gateway status
hermes gateway restart
hermes gateway install        # systemd, sobe no boot
journalctl --user -u hermes-gateway -f
hermes logs -f | grep -i adapter

Comandos exclusivos do gateway

10Modelos & custo

Trocar de modelo é uma linha, e é a alavanca mais direta de custo/qualidade.

/model                        # picker interativo, só nesta sessão
/model deepseek-v4-pro
/model opus --global          # grava no config
hermes fallback list          # cadeia de fallback quando um falha
hermes auth status            # credenciais e pools

Aliases configurados aqui

Heurística de escolha

11Segurança

O agente executa comandos reais na máquina. Trate como um operador com shell, porque é exatamente isso.

hermes security status
chmod 600 ~/.hermes/.env
hermes secrets bitwarden     # cofre externo opcional
hermes backup

12Receitas prontas

Pedidos que funcionam. Copie e adapte o caminho/nome.

Serviço sempre no ar

"O bot X precisa ficar online 24/7. Crie uma unit systemd de usuário com
Restart=always, RestartSec=3, enable --now, e confirme com systemctl --user
status que está active. Depois simule uma queda com kill e mostre que voltou."

Site estático com HTTPS

"Publique /root/site em https://app.72.61.27.32.sslip.io usando nginx +
certbot. No fim, me devolva o resultado de curl -I mostrando 200 e o
certificado válido. Não toque em nenhum outro vhost."

Pesquisa em paralelo com citações

"Pesquise X em 4 fontes independentes usando delegate_task em paralelo.
Cada subagente deve retornar trechos com URL de origem. Consolide em
/root/pesquisa.md com uma seção por fonte e uma conclusão citando os links."

Monitoramento com alerta

"Crie um cron diário às 9h que checa o preço de Y e me manda no Telegram
só se cair abaixo de Z. Rode uma vez agora com cron run para eu ver o formato."

Revisão antes de commitar

"Revise o diff de hoje procurando: segredo vazado, query sem índice,
falta de tratamento de erro em chamada externa, e código morto.
Liste por arquivo com linha. Não aplique nada ainda."

Transformar trabalho em ativo

"O que acabamos de fazer vai se repetir todo mês. Salve como skill
'subir-app-nginx' com os passos exatos, as armadilhas que encontramos
e o comando de verificação."

Recuperar contexto antigo

"Busque nas sessões antigas o que decidimos sobre a stack do app do
embarque e me resuma com a data de cada decisão."

Handoff para outro profile

hermes -p omega chat --query-file /root/handoff.txt

Contexto longo vai em arquivo, nunca colado no PTY — colagem grande trunca e trava o stream.

13Socorro

Higiene periódica

hermes doctor --fix          # mensal
hermes sessions prune --older 60d
hermes curator status        # skills paradas viram arquivo
hermes backup
hermes update

14Mapa de arquivos

As cinco regras que resumem tudo

1. Peça resultado, não plano. O agente tem mãos.
2. Dê contexto verificável. Caminho absoluto e erro cru valem mais que adjetivo.
3. Exija prova. “Está no ar” só conta com curl 200.
4. Feche o ciclo. Tarefa que vai repetir vira skill; fato estável vira memória.
5. Contexto limpo pensa melhor. /new quando muda o assunto, /compact quando incha.