Você tem uma assinatura Claude Max e usa o claude no terminal todos os dias. Naturalmente você quer o Hermes no mesmo plano: o agent que lembra das coisas entre sessões, rodando na cota que você já paga. Aí o assistente de configuração pede uma API key, você compra crédito medido para conseguir entrar, e no fim do mês está pagando pelos dois — com dois pools de franquia separados. Essa lacuna incômoda agora tem uma resposta oficial: apontar o Hermes para o próprio executável oficial claude.

O que o plugin realmente faz

O plugin é o Claude Subscription DirectSDK (Experimental), instalável como claude-subscription-directsdk-experimental. Ele dirige o executável oficial do Claude Code sem modificações como cliente de modelo escopado por requisição, então o trabalho roda na sua assinatura Claude Pro/Max — enquanto o Hermes mantém o seu próprio loop de agent: ferramentas, política de aprovação, compactação, memória e skills continuam todas do lado do Hermes.

O nome é um pouco enganoso. Apesar do “DirectSDK”, a implementação fala o protocolo nativo stream-json diretamente e não exige o pacote Python Agent SDK. O plugin declara a sua dependência do binário claude no plugin.yaml, em external_dependencies, mas não mantém credenciais próprias — a autenticação pertence ao CLI oficial, e o plugin nunca abre, copia, atualiza ou imprime os arquivos de credencial dele. Não existe fallback silencioso para HTTP com API key.

O que ele precisa:

• Hermes Agent 0.21.4 ou mais novo (ou a main em 118984d7a02f ou depois, a metade do core no PR #117451). Num Hermes mais antigo o plugin falha ao carregar com um aviso claro Failed to load user provider plugin, em vez de funcionar pela metade.
• Python 3.10+ no Linux, macOS ou Windows. A execução nativa roda no próprio grupo de processos e o cancelamento mata a árvore inteira, então o filho node por trás do shim npm nunca sobrevive a uma requisição cancelada.
• O CLI oficial do Claude Code, instalado e logado: npm install -g @anthropic-ai/claude-code, depois claude auth login.

O plugin é explícito sobre todo caminho em que o claude está faltando: no carregamento ele registra um aviso e continua registrado, para que a configuração possa explicar o que falta; o hermes model para com a dica de instalação e não escreve nada na config; uma requisição falha imediatamente com a mesma dica, em vez de um traceback de Popen.

Instalação e seleção

# 1) o CLI oficial (o plugin não armazena credenciais)
npm install -g @anthropic-ai/claude-code
claude auth login

# 2) instalar a partir do catálogo de plugins do Hermes (fixado, revisado)
hermes plugins install claude-subscription-directsdk

# ou direto do GitHub (acompanha a main)
hermes plugins install NousResearch/hermes-plugin-claude-subscription-directsdk

# 3) selecioná-lo
hermes model          # escolha "Claude Subscription DirectSDK (Experimental)"

Instalações por profile ficam em ~/.hermes/profiles/<profile>/plugins/. O plugin declara kind: model-provider, então a descoberta de providers o importa diretamente — sem necessidade de nenhuma entrada em plugins.enabled.

Para uma execução única:

hermes --provider claude-subscription-directsdk-experimental -m sonnet

Configuração persistente é o par de provider comum:

model:
  provider: claude-subscription-directsdk-experimental
  default: sonnet

Duas variáveis de ambiente importam em projetos reais: CLAUDE_CONFIG_DIR (ou a variante do lado do plugin, CLAUDE_SUBSCRIPTION_DIRECTSDK_CONFIG_DIR) para apontar para um diretório de autenticação do CLI gerenciado à parte, e CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND para um binário fora do PATH. Mais uma coisa a saber: se o ambiente de lançamento carrega um ANTHROPIC_API_KEY herdado, um endpoint Anthropic customizado ou um override de cloud backend, o caminho de cliente do Hermes recusa antes de gerar qualquer coisa — o erro nomeia as variáveis conflitantes sem imprimir os seus valores. Remova esses overrides quando quiser OAuth.

Uma chamada do Hermes, uma requisição upstream: o relé de admissão

Esta é a parte que vale entender. O Claude Code nativo 2.1.263 pode tentar gerações extras mesmo com --max-turns 1 e os retries HTTP desabilitados. Deixado solto, uma única chamada do Hermes poderia significar duas requisições upstream, dobrando silenciosamente o uso e o custo.

Então o plugin coloca um relé escopado por requisição no meio: ele encaminha apenas a primeira requisição Messages e rejeita as tentativas subsequentes localmente. O Hermes recebe a primeira resposta upstream concluída, com o seu usage real e o stop reason nativo, e uma recuperação nativa bloqueada não transforma uma resposta concluída em exceção — streams truncados e erros HTTP upstream continuam sendo falhas.

Os números de qualificação são a prova de que a fronteira de admissão se sustenta: uma revisão integrada apoiada na assinatura completou sete chamadas do Hermes com exatamente sete requisições upstream, doze execuções de ferramenta e doze resultados de ferramenta duráveis. O contexto cresceu de 138.498 para 165.697 tokens, as leituras de cache de acompanhamento ficaram em média 97,13 %, e a contabilidade nativa reportou $0.8793728 em equivalente de preço de lista.

O isolamento é construído do mesmo jeito: cada chat.completions.create inicia um processo novo num diretório temporário privado, com as ferramentas nativas, as skills e as fontes de configuração desabilitadas; o MCP anuncia apenas o inventário atual de ferramentas do Hermes, com callbacks inertes e execução negada pelo dontAsk nativo; o system prompt e os campos de geração viajam por arquivos privados para evitar o limite de comprimento por argumento do SO. Campos de autenticação e de identidade nunca são substituídos.

Faturamento: preço de lista não é uma fatura

A redação oficial aqui é deliberadamente cuidadosa, e vale guardá-la literalmente na cabeça. Quando todo modelo reportado carrega costBasis: list e o total é finito e não negativo, o Hermes registra esse valor como um equivalente estimado de preço de lista da API — ele não é a fatura da sua assinatura nem uma cobrança de uso extra, nunca é marcado como gratuito ou incluído, e nunca é substituído por preços de alias adivinhados. Contabilidade final ausente ou inválida permanece desconhecida, e uma requisição interrompida não pode ser lida como trabalho gratuito ou de zero tokens.

O que se reduz a duas frases: a franquia da assinatura e as configurações de uso extra pertencem à sua conta e ao serviço nativo — desabilite o uso extra na conta se você não quiser cobrança excedente; e uma estimativa nativa de preço de lista não é prova de uma cobrança da assinatura.

Duas armadilhas reais de cache (e como foram corrigidas)

Para qualquer design que “envelopa um CLI”, é no prompt caching que as coisas dão errado. O plugin documenta duas qualificações de contexto longo, e vale lê-las juntas.

Primeira: uma tarefa real de revisão com Sonnet 5 enviou 187.049 tokens de entrada na sua primeira requisição, e a rodada de ferramenta seguinte leu apenas 6.989 de 190.840 tokens de entrada do cache (3,66 %), reescrevendo 183.849 tokens no cache de uma hora. Testes com requisições idênticas a 179K tokens tinham passado — eles simplesmente nunca exercitaram essa fronteira de replay.

A causa era o lembrete nativo de orçamento de tokens injetado no contexto: o Hermes é dono dos orçamentos e reconstrói esse lembrete através da fronteira de cache durante o replay, então o prefixo deixou de ser estável. A correção foi desabilitar o lembrete nativo — sem marcadores de cache extras, sem mudança de TTL. Depois dela: uma revisão completa de sete chamadas com dez execuções reais de ferramenta fez o contexto crescer de 187K para 212K, com as requisições de acompanhamento em média 97,99 % de leituras de cache (85,45 % incluindo o cold start) e $1.1030034 na contabilidade nativa de preço de lista.

Leia as duas juntas e a conclusão é: o cache pode ser feito funcionar, e cargas de trabalho acima de cerca de 187K de contexto valem ser medidas antes de você se comprometer. Note também que estes são resultados do Sonnet 5 — o Fable 5.1 na mesma conta exigia créditos de uso pagos e não foi exercitado.

Limites e ressalvas

• Esta é uma build de revisão, não uma alegação de paridade total ou de prontidão para produção. O Claude Code nativo 2.1.263 é a versão qualificada; confirmações de replay e comportamento de extra-body são interfaces sensíveis à versão.
• Nomes de ferramenta passam pelo mapeamento mcp__hermes__, e os nomes originais precisam ser identificadores ASCII alfanuméricos/underscore/hífen únicos, de no máximo 50 caracteres.
• O texto flui de forma incremental, mas um lote completo de ferramentas só é publicado depois que o turno do assistente se assenta (message_stop nativo, usage final, saída do processo). O Hermes então aplica os seus próprios hooks, aprovações, ferramentas e persistência.
• A autocompactação nativa fica desabilitada para que o Hermes seja dono da compactação; isso não é o mesmo que paridade para toda transformação de histórico ou replay assinado entre modelos.
• Roteamento auxiliar e de fallback continuam sob o controle do host: configure-os explicitamente se eles também precisarem usar a assinatura. Este provider não muda silenciosamente os seus outros providers selecionados.

A versão curta

Se você tem tanto uma assinatura Claude Pro/Max quanto o Hermes, este plugin transforma “comprar um segundo pool de crédito de API” numa escolha: três comandos de instalação, escolha o provider, e o resto é o protocolo nativo do CLI oficial fazendo o trabalho. Só duas coisas realmente precisam das suas mãos — a configuração de uso extra na conta e o seu próprio ambiente (limpe overrides herdados como ANTHROPIC_API_KEY para que o caminho de cliente não recuse na inicialização). Para ver qual release carrega a metade do core da qual o plugin depende, leia o que a v0.21.4 realmente entregou; para o trabalho diário com modelos, veja a referência do comando hermes model e hooks de plugin de provider.