Documentação oficial desta página · v0.20.6
Dicas e Boas Práticas
Uma coleção de dicas práticas de ganho rápido que deixam você imediatamente mais eficiente com o Hermes Agent. Cada seção trata de um aspecto diferente — passe os olhos nos títulos e pule para o que interessa.
Rode hermes setup --portal — você ganha mais de 300 modelos, incluindo Claude, GPT-5 e Gemini, em uma única assinatura. Veja Nous Portal.
Como obter os melhores resultados
Seja específico sobre o que você quer
Prompts vagos produzem resultados vagos. Em vez de "conserta o código", diga "conserte o TypeError em api/handlers.py na linha 47 — a função process_request() recebe None de parse_body()". Quanto mais contexto você dá, menos iterações são necessárias.
Dê o contexto logo de cara
Comece o pedido já com os detalhes relevantes: caminhos de arquivo, mensagens de erro, comportamento esperado. Uma mensagem bem construída vale mais que três rodadas de esclarecimento. Cole os tracebacks de erro diretamente — o agente sabe interpretá-los.
Use arquivos de contexto para instruções recorrentes
Se você se pega repetindo as mesmas instruções ("use tabulação, não espaços", "nós usamos pytest", "a API fica em /api/v2"), coloque-as em um arquivo AGENTS.md. O agente lê esse arquivo automaticamente a cada sessão — esforço zero depois da configuração inicial.
Deixe o agente usar as ferramentas dele
Não tente conduzir cada passo pela mão. Diga "encontre e conserte o teste que está falhando" em vez de "abra tests/test_foo.py, olhe a linha 42, depois...". O agente tem busca em arquivos, acesso ao terminal e execução de código — deixe-o explorar e iterar.
Use skills para fluxos complexos
Antes de escrever um prompt longo explicando como fazer alguma coisa, verifique se já existe uma skill para isso. Digite /skills para navegar pelas skills disponíveis, ou invoque uma diretamente, como /axolotl ou /github-pr-workflow.
Dicas de usuário avançado da CLI
Entrada em várias linhas
Pressione Alt+Enter, Ctrl+J ou Shift+Enter para inserir uma quebra de linha sem enviar. Shift+Enter só funciona quando o terminal o envia como uma tecla distinta (Kitty / foot / WezTerm / Ghostty por padrão; iTerm2 / Alacritty / terminal do VS Code depois que o protocolo de teclado do Kitty é habilitado). As outras duas funcionam em qualquer terminal.
Detecção de colagem
A CLI detecta automaticamente colagens de várias linhas. Basta colar um bloco de código ou um traceback de erro diretamente — ela não envia cada linha como uma mensagem separada. A colagem fica em buffer e é enviada como uma mensagem só.
Interromper e redirecionar
Pressione Ctrl+C uma vez para interromper o agente no meio da resposta. Você pode então digitar uma nova mensagem para redirecioná-lo. Pressione Ctrl+C duas vezes em menos de 2 segundos para forçar a saída. Isso é valiosíssimo quando o agente começa a seguir pelo caminho errado.
Retome sessões com -c
Esqueceu algo da última sessão? Rode hermes -c para retomar exatamente de onde parou, com todo o histórico da conversa restaurado. Você também pode retomar pelo título: hermes -r "meu projeto de pesquisa".
Colar imagem da área de transferência
Pressione Ctrl+V para colar uma imagem da área de transferência direto no chat. O agente usa visão para analisar capturas de tela, diagramas, pop-ups de erro ou mockups de interface — sem precisar salvar em arquivo antes.
Autocompletar de comandos de barra
Digite / e pressione Tab para ver todos os comandos disponíveis. Isso inclui os comandos embutidos (/compress, /model, /title) e cada skill instalada. Você não precisa memorizar nada — o Tab resolve.
Use /verbose para alternar entre os modos de exibição da saída de ferramentas: off → new → all → verbose. O modo "all" é ótimo para acompanhar o que o agente faz; "off" é o mais limpo para perguntas e respostas simples.
Arquivos de contexto
AGENTS.md: o cérebro do seu projeto
Crie um AGENTS.md na raiz do projeto com decisões de arquitetura, convenções de código e instruções específicas do projeto. Ele é injetado automaticamente em toda sessão, então o agente sempre conhece as regras do seu projeto.
# Contexto do projeto
- Este é um backend FastAPI com ORM SQLAlchemy
- Sempre use async/await para operações de banco de dados
- Testes ficam em tests/ e usam pytest-asyncio
- Nunca faça commit de arquivos .env
SOUL.md: personalize a personalidade
Quer que o Hermes tenha uma voz padrão estável? Edite ~/.hermes/SOUL.md (ou $HERMES_HOME/SOUL.md, se você usa um diretório home do Hermes personalizado). O Hermes agora cria um SOUL inicial automaticamente e usa esse arquivo global como fonte de personalidade para toda a instância.
Para um passo a passo completo, veja Use o SOUL.md com o Hermes.
# Soul
Você é um engenheiro de backend sênior. Seja conciso e direto.
Pule as explicações a menos que peçam. Prefira soluções de uma linha às verbosas.
Sempre considere tratamento de erros e casos de borda.
Use o SOUL.md para personalidade duradoura. Use o AGENTS.md para instruções específicas do projeto.
Compatibilidade com .cursorrules
Já tem um arquivo .cursorrules ou .cursor/rules/*.mdc? O Hermes lê esses também. Não precisa duplicar suas convenções de código — elas são carregadas automaticamente do diretório de trabalho.
Descoberta
O Hermes carrega o AGENTS.md de nível superior do diretório de trabalho atual no início da sessão. Arquivos AGENTS.md em subdiretórios são descobertos sob demanda durante as chamadas de ferramenta (via subdirectory_hints.py) e injetados nos resultados das ferramentas — eles não são carregados de antemão no prompt de sistema.
Mantenha os arquivos de contexto focados e concisos. Cada caractere pesa no seu orçamento de tokens, já que eles são injetados em cada uma das mensagens.
Memória e skills
Memória x skills: o que vai onde
Memória é para fatos: seu ambiente, preferências, localização dos projetos e coisas que o agente aprendeu sobre você. Skills são para procedimentos: fluxos de vários passos, instruções específicas de ferramentas e receitas reutilizáveis. Use memória para o "o quê", skills para o "como".
Quando criar skills
Se você encontrar uma tarefa que leva 5 passos ou mais e que vai repetir, peça ao agente para criar uma skill para ela. Diga "salve o que você acabou de fazer como uma skill chamada deploy-staging". Da próxima vez, é só digitar /deploy-staging e o agente carrega o procedimento completo.
Como administrar a capacidade da memória
A memória é limitada de propósito (cerca de 2.200 caracteres para o MEMORY.md, cerca de 1.375 para o USER.md). Quando enche, o agente consolida as entradas. Você pode ajudar dizendo "limpe a sua memória" ou "substitua a anotação antiga sobre Python 3.9 — estamos no 3.12 agora".
Deixe o agente lembrar
Depois de uma sessão produtiva, diga "lembre disso para a próxima vez" e o agente salva as conclusões principais. Você também pode ser específico: "salve na memória que a nossa CI usa GitHub Actions com o workflow deploy.yml".
A memória é um retrato congelado — mudanças feitas durante a sessão só aparecem no prompt de sistema na sessão seguinte. O agente escreve em disco na hora, mas o cache do prompt não é invalidado no meio da sessão.
Desempenho e custo
Não quebre o cache do prompt
A maioria dos provedores de LLM faz cache do prefixo da conversa (prompt de sistema + histórico). Se você mantiver o prompt de sistema estável (mesmos arquivos de contexto, mesma memória), as mensagens seguintes da sessão ganham acertos de cache bem mais baratos. O cache é indexado pelo modelo e pela conta — então uma troca explícita com /model, um recuo automático de provedor ou um rodízio de pool de credenciais forçam o próximo turno a reler a conversa inteira pelo preço cheio de entrada. Trocas ocasionais tudo bem; trocar com frequência numa sessão longa multiplica o seu custo.
Use /compress antes de bater no limite
Sessões longas acumulam tokens. Quando você notar as respostas ficando lentas ou truncadas, rode /compress. Ele resume o histórico da conversa, preservando o contexto essencial e reduzindo drasticamente a contagem de tokens. Use /usage para ver como está a sua situação.
Delegue para trabalho em paralelo
Precisa pesquisar três assuntos ao mesmo tempo? Peça ao agente para usar o delegate_task com subtarefas paralelas. Cada subagente roda de forma independente, com o próprio contexto, e só os resumos finais voltam — o que reduz muito o uso de tokens da sua conversa principal.
Use execute_code para operações em lote
Em vez de rodar comandos de terminal um por um, peça ao agente para escrever um script que faça tudo de uma vez. "Escreva um script Python para renomear todos os arquivos .jpeg para .jpg e rode ele" é mais barato e mais rápido do que renomear arquivo por arquivo.
Escolha o modelo certo
Use /model para trocar de modelo no meio da sessão. Use um modelo de ponta (Claude Sonnet/Opus, GPT-4o) para raciocínio complexo e decisões de arquitetura. Troque para um modelo mais rápido em tarefas simples, como formatação, renomeação ou geração de boilerplate. Lembre que cada troca zera o cache do prompt (veja acima), então em sessões longas costuma sair mais barato começar uma sessão nova no outro modelo do que ficar indo e voltando.
Rode /usage de vez em quando para ver o seu consumo de tokens. Rode /insights para uma visão mais ampla dos padrões de uso dos últimos 30 dias. Para saber qual é o seu custo fixo por mensagem antes de qualquer conversa — prompt de sistema, índice de skills, memória, esquemas de ferramentas — rode hermes prompt-size (funciona offline).
Dicas de mensageria
Defina um canal casa
Use /sethome no seu chat preferido do Telegram ou Discord para designá-lo como canal casa. Resultados de tarefas cron e saídas de tarefas agendadas são entregues ali. Sem isso, o agente não tem para onde mandar mensagens proativas.
Use /title para organizar sessões
Dê nome às suas sessões com /title auth-refactor ou /title research-llm-quantization. Sessões nomeadas são fáceis de achar com hermes sessions list e de retomar com hermes -r "auth-refactor". Sessões sem nome se acumulam e ficam impossíveis de distinguir.
Pareamento por DM para acesso do time
Em vez de coletar IDs de usuário na mão para as listas de permissão, habilite o pareamento por DM. Quando um colega manda DM para o bot, ele recebe um código de pareamento de uso único. Você aprova com hermes pairing approve telegram XKGH5N7P — simples e seguro.
Modos de exibição do progresso de ferramentas
Use /verbose para controlar quanta atividade de ferramenta você vê. Em plataformas de mensagem, menos costuma ser mais — deixe em "new" para ver apenas as novas chamadas de ferramenta. Na CLI, o "all" dá uma visão ao vivo bem satisfatória de tudo o que o agente faz.
Por padrão, sessões de mensageria nunca se reiniciam sozinhas — o contexto vive até você dar /reset ou a compressão entrar em ação. Se você quer que as sessões reiniciem automaticamente (depois de um tempo ocioso ou diariamente em uma hora fixa), habilite pela seção session_reset do ~/.hermes/config.yaml.
Segurança
Use Docker para código não confiável
Ao trabalhar com repositórios não confiáveis ou rodar código desconhecido, use Docker ou Daytona como backend de terminal. Defina TERMINAL_ENV=docker no seu .env. Comandos destrutivos dentro de um contêiner não conseguem danificar o sistema hospedeiro.
# No seu .env:
TERMINAL_ENV=docker
TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest
Evite as armadilhas de codificação do Windows
No Windows, algumas codificações padrão (como cp125x) não conseguem representar todos os caracteres Unicode, o que pode causar UnicodeEncodeError ao escrever arquivos em testes ou scripts.
- Prefira abrir arquivos com codificação UTF-8 explícita:
with open("resultados.txt", "w", encoding="utf-8") as f:
f.write("✓ Tudo certo\n")
- No PowerShell, você também pode passar a sessão atual para UTF-8 no console e na saída de comandos nativos:
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
Isso mantém o PowerShell e os processos filhos em UTF-8 e ajuda a evitar falhas que só acontecem no Windows.
Pense antes de escolher "always"
Quando o agente dispara uma aprovação de comando perigoso (rm -rf, DROP TABLE etc.), você recebe quatro opções: once, session, always, deny. Pense bem antes de escolher "always" — isso coloca aquele padrão na lista de permissão permanentemente. Comece pelo "session" até se sentir confortável.
A aprovação de comandos é a sua rede de segurança
O Hermes confere todo comando contra uma lista curada de padrões perigosos antes de executar. Isso inclui remoções recursivas, drops de SQL, canalizar curl para o shell e mais. Não desabilite isso em produção — existe por bons motivos.
Ao rodar em um backend de contêiner (Docker, Singularity, Modal, Daytona), as checagens de comando perigoso são puladas, porque o contêiner é a fronteira de segurança. Garanta que as suas imagens de contêiner estejam devidamente trancadas.
Use listas de permissão em bots de mensageria
Nunca defina GATEWAY_ALLOW_ALL_USERS=true em um bot com acesso ao terminal. Sempre use listas de permissão específicas da plataforma (TELEGRAM_ALLOWED_USERS, DISCORD_ALLOWED_USERS) ou pareamento por DM para controlar quem pode interagir com o seu agente.
# Recomendado: listas de permissão explícitas por plataforma
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
# Ou use a lista de permissão multiplataforma
GATEWAY_ALLOWED_USERS=123456789,987654321
Tem uma dica que deveria estar nesta página? Abra uma issue ou um PR — contribuições da comunidade são bem-vindas.