Plugins Embutidos

O Hermes traz um conjunto pequeno de plugins junto com o repositório. Eles ficam em <repo>/plugins/<nome>/ e carregam automaticamente ao lado dos plugins instalados por você em ~/.hermes/plugins/. Usam a mesma superfície dos plugins de terceiros — hooks, ferramentas, comandos de barra — só que mantidos dentro da árvore do projeto.

Veja a página Plugins para o sistema de plugins em geral, e Criar um plugin do Hermes para escrever o seu.

Como funciona a descoberta

O PluginManager varre quatro fontes, nesta ordem:

1. Embutida — <repo>/plugins/<nome>/ (o que esta página documenta)
2. Da pessoa — ~/.hermes/plugins/<nome>/
3. Do projeto — ./.hermes/plugins/<nome>/ (exige HERMES_ENABLE_PROJECT_PLUGINS=1)
4. Pontos de entrada do pip — hermes_agent.plugins

Em caso de colisão de nome, as fontes posteriores vencem — um plugin seu chamado disk-cleanup substituiria o embutido.

plugins/memory/ e plugins/context_engine/ ficam deliberadamente de fora da varredura de embutidos. Esses diretórios usam caminhos próprios de descoberta, porque provedores de memória e motores de contexto são provedores de escolha única, configurados por hermes memory setup / context.engine na configuração.

Plugins embutidos são opt-in

Os plugins embutidos vêm desligados. A descoberta acha todos (eles aparecem em hermes plugins list e na interface interativa hermes plugins), mas nenhum carrega até você habilitá-lo explicitamente:

hermes plugins enable disk-cleanup

Ou pelo ~/.hermes/config.yaml:

plugins:
  enabled:
    - disk-cleanup

É o mesmo mecanismo que os plugins instalados por você usam. Plugins embutidos nunca são habilitados sozinhos — nem em instalação nova, nem para quem já usa e atualiza para um Hermes mais novo. Você sempre escolhe explicitamente.

Para desligar um plugin embutido de novo:

hermes plugins disable disk-cleanup
# ou: remova-o de plugins.enabled no config.yaml

O que vem hoje

O repositório traz estes plugins embutidos em plugins/. Todos são opt-in — habilite com hermes plugins enable <nome>.

Plugin	Tipo	Para que serve
disk-cleanup	hooks + comando de barra	Rastreia arquivos efêmeros automaticamente e limpa no fim da sessão
security-guidance	hooks	Casa padrões de código perigoso em write_file/patch e acrescenta um aviso de segurança (ou bloqueia) — 25 regras (fork Apache-2.0 dos padrões do claude-plugins-official da Anthropic)
observability/langfuse	hooks	Envia rastros de turnos, chamadas de LLM e ferramentas para o Langfuse
teams_pipeline	autônomo	Pipeline de reuniões do Microsoft Teams — resumos de reunião baseados no Graph, transcrição primeiro
spotify	backend (7 ferramentas)	Reprodução, fila, busca, playlists, álbuns e biblioteca nativos do Spotify
google_meet	autônomo	Entra em chamadas do Meet, transcrição por legenda ao vivo, áudio duplex em tempo real opcional
image_gen/openai	backend de imagem	Backend de geração de imagem gpt-image-2 da OpenAI (alternativa ao FAL)
image_gen/openai-codex	backend de imagem	Geração de imagem da OpenAI via OAuth do Codex
image_gen/xai	backend de imagem	Backend grok-2-image da xAI
hermes-achievements	aba do painel	Emblemas colecionáveis no estilo Steam, gerados a partir do seu histórico real de sessões do Hermes
kanban/dashboard	aba do painel	Interface de quadro kanban para o despachante multiagente — tarefas, comentários, fan-out, troca de quadro. Veja Kanban multiagente.

Provedores de memória (plugins/memory/*) e motores de contexto (plugins/context_engine/*) estão listados à parte em Provedores de memória — eles são gerenciados por hermes memory e hermes plugins, respectivamente. O detalhamento completo dos dois plugins de longa data baseados em hooks vem a seguir.

disk-cleanup

Rastreia e remove automaticamente arquivos efêmeros criados durante as sessões — scripts de teste, saídas temporárias, logs de cron, perfis do chrome parados — sem exigir que o agente se lembre de chamar uma ferramenta.

Como funciona:

Hook	Comportamento
post_tool_call	Quando write_file / terminal / patch cria um arquivo que casa com test_*, tmp_* ou *.test.* dentro de HERMES_HOME ou de /tmp/hermes-*, rastreia em silêncio como test / temp / cron-output.
on_session_end	Se algum arquivo de teste foi rastreado automaticamente durante o turno, roda a limpeza segura quick e registra um resumo de uma linha. Fica calado no resto do tempo.

Regras de exclusão:

Categoria	Limiar	Confirmação
test	todo fim de sessão	Nunca
temp	mais de 7 dias desde o rastreio	Nunca
cron-output	mais de 14 dias desde o rastreio	Nunca
diretórios vazios dentro de HERMES_HOME	sempre	Nunca
research	mais de 30 dias, além dos 10 mais novos	Sempre (só na deep)
chrome-profile	mais de 14 dias desde o rastreio	Sempre (só na deep)
arquivos com mais de 500 MB	nunca automático	Sempre (só na deep)

Comando de barra — /disk-cleanup disponível tanto na CLI quanto nas sessões de gateway:

/disk-cleanup status                     # detalhamento + os 10 maiores
/disk-cleanup dry-run                    # prévia sem apagar
/disk-cleanup quick                      # roda a limpeza segura agora
/disk-cleanup deep                       # quick + lista dos itens que precisam de confirmação
/disk-cleanup track <caminho> <categoria> # rastreio manual
/disk-cleanup forget <caminho>           # para de rastrear (não apaga)

Estado — tudo fica em $HERMES_HOME/disk-cleanup/:

Arquivo	Conteúdo
tracked.json	Caminhos rastreados com categoria, tamanho e data/hora
tracked.json.bak	Backup de escrita atômica do arquivo acima
cleanup.log	Trilha de auditoria só de acréscimo, com todo rastreio / pulo / rejeição / exclusão

Segurança — a limpeza só toca em caminhos dentro de HERMES_HOME ou de /tmp/hermes-*. Montagens do Windows (/mnt/c/...) são rejeitadas. Diretórios de estado bem conhecidos no primeiro nível (logs/, memories/, sessions/, cron/, cache/, skills/, plugins/ e o próprio disk-cleanup/) nunca são removidos, mesmo vazios — uma instalação nova não é esvaziada no primeiro fim de sessão.

Para habilitar: hermes plugins enable disk-cleanup (ou marque a caixa em hermes plugins).

Para desabilitar de novo: hermes plugins disable disk-cleanup.

security-guidance

Avisos rápidos de segurança por casamento de padrão nas escritas de arquivo. Quando as chamadas de write_file / patch / skill_manage do agente carregam conteúdo que casa com um padrão de código sabidamente perigoso — pickle.load, yaml.load sem SafeLoader, eval(, os.system, subprocess(..., shell=True), child_process.exec em JS, dangerouslySetInnerHTML do React, .innerHTML = / .outerHTML = / document.write crus, crypto.createCipher do Node, modo AES ECB, verificação de TLS desligada, parsers xml.etree / minidom sujeitos a XXE, <script src="//..." > sem SRI, torch.load sem weights_only=True, injeção de ${{ github.event.* }} no GitHub Actions — o plugin acrescenta um bloco ⚠️ Security guidance ao resultado da ferramenta.

O arquivo é escrito mesmo assim. O modelo lê o aviso na mensagem de ferramenta do turno seguinte e pode corrigir o código ou documentar por que a construção é segura naquele contexto. O casamento de padrão tem uma taxa não trivial de falso positivo, e é por isso que avisar (e não bloquear) é o padrão.

Cobertura: 25 regras no total, cobrindo desserialização insegura, injeção de comando, sumidouros de XSS, armadilhas de criptografia, XXE, cadeia de suprimentos (SRI) e injeção em fluxos de CI/CD. Os dados de padrão são um fork Apache-2.0 literal do claude-plugins-official da Anthropic — veja os arquivos LICENSE e NOTICE do plugin para a atribuição.

Modos:

Variável de ambiente	Efeito
(não definida)	modo de aviso (padrão) — o arquivo é escrito, o aviso é anexado ao resultado
SECURITY_GUIDANCE_BLOCK=1	modo de bloqueio — a escrita é recusada, o aviso volta como motivo do bloqueio
SECURITY_GUIDANCE_DISABLE=1	interruptor geral — o plugin carrega, mas não faz nada

Para habilitar: hermes plugins enable security-guidance (ou marque a caixa em hermes plugins).

Para desabilitar de novo: hermes plugins disable security-guidance.

O que ele ainda não faz: o plugin original da Anthropic tem mais duas camadas — uma revisão do diff por LLM a cada turno do agente que mexeu em arquivos, e uma revisão agêntica na hora do commit que segue o fluxo de dados entre arquivos. Nenhuma das duas foi portada. O agente já consegue rodar essas revisões sob demanda com delegate_task.

observability/langfuse

Envia rastros de turnos, chamadas de LLM e invocações de ferramenta do Hermes para o Langfuse — uma plataforma de observabilidade de LLM de código aberto. Um span por turno, uma geração por chamada de API, uma observação de ferramenta por chamada de ferramenta. Os totais de uso, as contagens de token por tipo e as estimativas de custo saem dos números canônicos de agent.usage_pricing do Hermes, então o painel do Langfuse vê o mesmo detalhamento (entrada / saída / cache_read_input_tokens / cache_creation_input_tokens / reasoning_tokens) que aparece em hermes logs.

O plugin falha em aberto: sem SDK instalado, sem credenciais ou com um erro passageiro do Langfuse, tudo vira um no-op silencioso no hook. O laço do agente nunca é afetado.

Configuração (interativa — recomendada):

hermes tools          # → Langfuse Observability → Cloud ou Self-Hosted

O assistente coleta as suas chaves, roda pip install do SDK langfuse e adiciona observability/langfuse a plugins.enabled para você. Reinicie o Hermes e o próximo turno já manda um rastro.

Configuração (manual):

pip install langfuse
hermes plugins enable observability/langfuse

Depois, coloque as credenciais em ~/.hermes/.env:

HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com   # ou a URL da sua instalação própria

Como funciona:

Hook	Comportamento
pre_api_request / pre_llm_call	Abre (ou reaproveita) um span raiz por turno, "Hermes turn". Começa uma observação filha do tipo generation para esta chamada de API, com as mensagens recentes serializadas como entrada.
post_api_request / post_llm_call	Fecha a geração e anexa usage_details, cost_details, finish_reason, a saída do assistente e as chamadas de ferramenta. Se não houve chamadas de ferramenta e o conteúdo não está vazio, fecha o turno.
pre_tool_call	Começa uma observação filha do tipo tool com os args higienizados.
post_tool_call	Fecha a observação de ferramenta com o result higienizado. Cargas de read_file são resumidas (início + fim + contagem de linhas omitidas) para a leitura de um arquivo enorme continuar abaixo de HERMES_LANGFUSE_MAX_CHARS.

O agrupamento de sessão usa como chave o ID de sessão do Hermes (ou o ID de tarefa, no caso de subagentes) via langfuse.propagate_attributes, então tudo dentro de uma mesma sessão de hermes chat fica sob uma única sessão do Langfuse.

Para conferir:

hermes plugins list                 # observability/langfuse deve aparecer como "enabled"
hermes chat -q "hello"              # procure um rastro "Hermes turn" na interface do Langfuse

Ajustes opcionais (no .env):

Variável	Padrão	Para que serve
HERMES_LANGFUSE_ENV	—	Marcador de ambiente nos rastros (production, staging, …)
HERMES_LANGFUSE_RELEASE	—	Marcador de release/versão
HERMES_LANGFUSE_SAMPLE_RATE	1.0	Taxa de amostragem passada ao SDK (0.0–1.0)
HERMES_LANGFUSE_MAX_CHARS	12000	Corte por campo do conteúdo das mensagens, dos argumentos e dos resultados de ferramenta
HERMES_LANGFUSE_DEBUG	false	Log verboso do plugin em agent.log

Tanto as variáveis com prefixo do Hermes quanto as padrão do SDK (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL) são aceitas — as com prefixo do Hermes vencem quando as duas estão definidas.

Desempenho: o cliente do Langfuse fica em cache depois da primeira chamada de hook. Se as credenciais ou o SDK estiverem faltando, essa decisão também fica em cache — os hooks seguintes retornam rápido, sem reconferir variáveis de ambiente nem recarregar a configuração.

Para desabilitar: hermes plugins disable observability/langfuse. O módulo do plugin continua sendo descoberto, mas nenhum código dele roda até você reabilitar.

Integração nativa com o NeMo Relay (nota de migração)

O NeMo Relay não é mais um plugin embutido do Hermes. Não rode hermes plugins enable observability/nemo_relay; o núcleo do Hermes agora é dono dos ciclos de vida de sessão, turno, LLM e ferramenta do Relay.

Para optar por middlewares ou exportadores do Relay, crie um plugins.toml padrão do Relay e depois aponte HERMES_NEMO_RELAY_PLUGINS_TOML para esse arquivo antes de iniciar o Hermes. A política vale para o processo inteiro, para todos os perfis hospedados naquele processo do Hermes. Veja a configuração de observabilidade do NeMo Relay para as opções de ATOF, ATIF e OpenTelemetry.

As antigas configurações HERMES_NEMO_RELAY_ATOF_* e HERMES_NEMO_RELAY_ATIF_* não ativam mais exportadores. O hermes doctor reporta essas configurações obsoletas quando nenhum plugins.toml substituto está selecionado.

Segmentação do span de sessão (sessões contínuas)

O Relay exporta um span quando o escopo dele fecha. Uma sessão contínua de gateway pode manter o span de sessão aberto por dias, mesmo com cada span de turno exportando normalmente. A segmentação opcional gira apenas o escopo de sessão, em uma fronteira de turno:

gateway:
  telemetry:
    session_segments:
      on_compaction: false  # gira depois da compressão de contexto
      max_turns: 0          # 0 = ilimitado; N = turnos por segmento

Chave	Padrão	Comportamento
on_compaction	false	Gira depois que a compressão termina, na próxima fronteira de turno.
max_turns	0	Gira a cada N turnos concluídos; 0 desliga o limite.

Os dois padrões preservam um único escopo de sessão para a sessão inteira. Os spans girados mantêm o mesmo session_id e acrescentam hermes.session.segment e hermes.session.segment_reason (compaction ou max_turns).

google_meet

Deixa o agente entrar em chamadas do Google Meet, transcrevê-las e participar delas — anotar uma reunião, resumir o vaivém depois, retomar pontos específicos e (opcionalmente) falar respostas de volta na chamada por TTS.

O que ele acrescenta:

• Um participante virtual sem interface que entra em uma URL do Meet por automação de navegador
• Transcrição ao vivo do áudio da reunião pelo provedor de STT configurado
• Um conjunto de ferramentas meet_join / meet_status / meet_transcript / meet_leave / meet_say que o agente aciona para entrar em chamadas, consultar a transcrição ao vivo e agir sobre o que ouviu
• Artefatos pós-reunião (transcrição, status) salvos em ~/.hermes/workspace/meetings/<meeting_id>/

Configuração:

hermes plugins enable google_meet
hermes meet setup   # pré-checagem: playwright, chromium, arquivo de autenticação
hermes meet auth    # abre um navegador para entrar no Google e salva o estado da sessão —
                    # precisa de uma conta Google com acesso ao Meet. A aprovação do anfitrião pode
                    # ser necessária se a reunião exigir "só participantes convidados podem entrar".

Uso no chat:

"Entre em meet.google.com/abc-defg-hij e faça anotações. Depois da chamada, me mande um resumo com itens de ação."

O agente inicia a entrada na reunião, transmite a transcrição de volta para o contexto dele conforme a chamada avança e produz um resumo estruturado quando a reunião acaba (ou quando você manda parar).

Quando usar: dailies recorrentes em que você quer um bot para transcrever e resumir para quem acompanha de forma assíncrona; entrevistas em estilo de depoimento em que você quer anotações estruturadas; qualquer caso em que você precisaria de Fireflies / Otter / Grain. Quando você preferir não ter uma IA escutando — não habilite.

Para desabilitar: hermes plugins disable google_meet. As transcrições salvas continuam em ~/.hermes/workspace/meetings/ até você removê-las.

hermes-achievements

Acrescenta uma aba de conquistas no estilo Steam ao painel — mais de 60 emblemas colecionáveis e em níveis, gerados do seu histórico real de sessões do Hermes. Façanhas de cadeia de ferramentas, padrões de depuração, sequências de vibe coding, uso de skills e memória, variedade de modelos e provedores, manias de estilo de vida (sessões de fim de semana e de madrugada). Escrito originalmente por @PCinkusz como plugin externo; trazido para dentro da árvore do projeto para acompanhar as mudanças de recurso do Hermes.

Como funciona:

• Varre todo o seu histórico de sessões em ~/.hermes/state.db no backend do painel
• As estatísticas por sessão ficam em cache pela impressão digital (started_at, last_active), então só sessões novas ou alteradas são reanalisadas nas varreduras seguintes
• A primeiríssima varredura roda em uma thread de segundo plano — o painel nunca fica travado esperando, nem em bancos com milhares de sessões
• O estado de desbloqueio é persistido em $HERMES_HOME/plugins/hermes-achievements/state.json

Progressão de níveis: Cobre → Prata → Ouro → Diamante → Olimpiano. Cada cartão expõe uma seção "O que conta", listando exatamente qual métrica está sendo acompanhada.

Estados das conquistas:

Estado	Significado
Desbloqueada	Pelo menos um nível conquistado
Descoberta	Conquista conhecida, progresso visível, ainda não conquistada
Secreta	Escondida até o Hermes detectar o primeiro sinal relacionado no seu histórico

API — as rotas ficam sob /api/plugins/hermes-achievements/:

Endpoint	Para que serve
GET /achievements	Catálogo completo com o estado de desbloqueio por emblema (devolve um marcador pendente enquanto a primeira varredura fria está rodando)
GET /scan-status	Estado do varredor de segundo plano: idle / running / failed, duração da última execução, número de execuções
GET /recent-unlocks	Os vinte emblemas desbloqueados mais recentemente, do mais novo ao mais antigo
GET /sessions/{id}/badges	Emblemas conquistados principalmente em uma sessão específica
POST /rescan	Revarredura manual e síncrona (trava; use quando a pessoa clicar no botão de revarredura)
POST /reset-state	Limpa o histórico de desbloqueios e o retrato em cache

Arquivos de estado — ficam em $HERMES_HOME/plugins/hermes-achievements/:

Arquivo	Conteúdo
state.json	Histórico de desbloqueios: quais emblemas você conquistou e quando. Estável entre atualizações do Hermes.
scan_snapshot.json	Carga da última varredura concluída (servida na hora ao carregar o painel)
scan_checkpoint.json	Cache de estatísticas por sessão, com chave de impressão digital (deixa as revarreduras quentes rápidas)

Notas de desempenho:

• Uma varredura fria em cerca de 8.000 sessões leva alguns minutos. Ela roda em uma thread de segundo plano na primeira requisição do painel; a interface vê um marcador pendente e consulta /scan-status.
• Resultados incrementais durante a varredura fria — o varredor publica um retrato parcial a cada ~250 sessões, então cada atualização do painel mostra mais emblemas desbloqueados conforme a varredura avança. Nada de encarar zeros por minutos a fio.
• A revarredura quente reaproveita as estatísticas por sessão de toda sessão cuja impressão digital started_at + last_active bate com o checkpoint — termina em segundos, mesmo em históricos grandes.
• O TTL do retrato em memória é de 120 s; requisições vencidas recebem o retrato antigo na hora e disparam uma atualização em segundo plano. Você nunca fica olhando para um carregando só porque o TTL expirou.

Para habilitar: não há nada a habilitar — hermes-achievements é um plugin só de painel (sem hooks de ciclo de vida, sem ferramentas visíveis para o modelo). Ele se registra sozinho como aba no hermes dashboard na primeira execução. A configuração plugins.enabled só controla plugins de ciclo de vida e de ferramentas; plugins de painel são descobertos puramente pelo dashboard/manifest.json deles.

Para optar por não usar: apague ou renomeie plugins/hermes-achievements/dashboard/manifest.json, ou sobrescreva-o com um plugin seu de mesmo nome em ~/.hermes/plugins/hermes-achievements/ que não traga painel. Os arquivos de estado do plugin em $HERMES_HOME/plugins/hermes-achievements/ sobrevivem — reinstalar preserva o seu histórico de desbloqueios.

Acrescentar um plugin embutido

Plugins embutidos são escritos exatamente como qualquer outro plugin do Hermes — veja Criar um plugin do Hermes. As únicas diferenças são:

• O diretório fica em <repo>/plugins/<nome>/ em vez de ~/.hermes/plugins/<nome>/
• A origem do manifesto é reportada como bundled em hermes plugins list
• Plugins da pessoa com o mesmo nome sobrescrevem a versão embutida

Um plugin é bom candidato a virar embutido quando:

• Não tem dependências opcionais (ou elas já estão nas dependências de pip install .[all])
• O comportamento beneficia a maioria das pessoas e é opt-out em vez de opt-in
• A lógica se conecta a hooks de ciclo de vida que o agente teria que lembrar de acionar de outra forma
• Complementa uma capacidade central sem ampliar a superfície de ferramentas visível ao modelo

Contraexemplos — coisas que devem continuar como plugins instaláveis pela pessoa, e não embutidos: integrações de terceiros com chaves de API, fluxos de nicho, árvores grandes de dependência, e qualquer coisa que mudasse o comportamento do agente de forma relevante por padrão.

---