O que você vai montar

Neste hands-on você coloca um agente de código — um assistente que lê seus arquivos, roda comandos e escreve código — funcionando na sua assinatura do Claude, sem chave de API e sem cobrança por token. No fim, ele tem canal próprio no Telegram, memória separada do seu assistente principal e uma rede de segurança para não ficar mudo quando a cota estourar.

Todo o caminho foi executado de ponta a ponta antes de virar texto. Os três tropeços que aparecem no meio estão marcados: são exatamente os que fazem a maioria das pessoas concluir, errado, que "a integração não funciona".

Pré-requisitos

  • Node.js instalado (o CLI do Claude Code roda em cima dele).
  • Assinatura Claude Pro ou Max ativa, com o CLI já autenticado na sua conta.
  • Um agente capaz de executar comandos no terminal (aqui usamos o Hermes Agent, mas o procedimento vale para qualquer um que rode shell).
  • Opcional: um bot novo criado no @BotFather, se você quiser o canal no Telegram.

Passo 1 — Confira a versão do Claude Code antes de qualquer coisa

Este é o passo que economiza horas de depuração. O agente depende de um CLI recente: versões antigas não sabem reenviar o histórico da conversa para o modelo, e o sintoma é traiçoeiro — o primeiro turno responde normalmente e o segundo quebra.

claude --version

Se a versão for anterior à 2.1.258, atualize antes de seguir. O erro que aparece no segundo turno é este:

Native history replay not supported: expected zero-turn acknowledgment

Parece falha temporária de servidor (a mensagem chega a sugerir "espere um minuto e tente de novo"). Não é: é incompatibilidade de versão. Nenhum retry resolve.

Passo 2 — Atualize sem deixar o CLI quebrado

npm install -g @anthropic-ai/claude-code@latest

Dois cuidados que valem escrever em pedra, porque os dois já queimaram gente de verdade:

  • Nunca interrompa o download no meio. Se você matar o processo (timeout, Ctrl+C, fechar o terminal), o pacote fica instalado sem o binário nativo e o CLI para de funcionar com Error: claude native binary not installed.
  • Se aparecer aviso de allow-scripts, o npm moderno bloqueou o script de instalação — é ele que baixa o binário nativo. O comando de aprovar scripts só vale para projeto local, não para instalação global; o conserto é rodar o postinstall à mão:
cd ~/.local/lib/node_modules/@anthropic-ai/claude-code
node install.cjs

Rode claude --version de novo: deve responder a versão nova. Só siga depois disso.

Passo 3 — Crie um agente separado do seu assistente principal

Colocar o programador dentro do assistente que você usa para tudo mistura contexto, memória e permissões. Crie um agente próprio, com identidade própria:

hermes profile create dev --clone --description "Programador"

No perfil novo, três ajustes:

  1. Aponte o modelo para a rota da assinatura, para os turnos rodarem no CLI em vez de numa API paga.
  2. Escreva a "alma" dele — o arquivo de instruções. Vale definir: idioma, o que ele faz antes de mexer em arquivo, quando ele precisa pedir sua confirmação e a regra de ouro de entregar resultado verificado em vez de "deve funcionar".
  3. Limpe o que veio do clone: tokens de outros bots e credenciais de integrações que esse agente não deve ter.

Passo 4 — Dê um canal próprio (e feche a porta)

Crie o bot no @BotFather e ponha o token no arquivo de segredos do perfil — nunca no arquivo de configuração versionado:

TELEGRAM_BOT_TOKEN=<token do BotFather>
TELEGRAM_HOME_CHANNEL=<seu id de usuário>
GATEWAY_ALLOWED_USERS=<seu id de usuário>

A última linha é a mais importante e a mais esquecida: sem allowlist, qualquer pessoa que descobrir o bot conversa com o seu agente — e o seu agente tem acesso ao seu terminal. Depois de gravar, ajuste a permissão do arquivo para 600.

Passo 5 — Configure um fallback, senão ele fica mudo

Assinatura também tem limite, e quando a cota estoura o agente responde "modelo indisponível" e para. Aponte um provedor de reserva:

fallback_providers:
  - provider: deepseek
    model: deepseek-v4-flash

Aqui mora uma pegadinha silenciosa: se você escrever a lista simples de nomes (fallback_providers: [deepseek]), o arquivo é aceito, a configuração parece certa — e a cadeia de reserva é descartada sem aviso. O agente continua sem fallback. Confirme com:

hermes fallback list

Só considere pronto quando a saída listar o provedor de reserva.

Passo 6 — Teste do jeito certo: dois turnos e uma ferramenta

Teste de um turno só passa em agente quebrado. Faça os três:

  1. Mande um "oi" e confirme a resposta.
  2. Na mesma conversa, mande uma segunda mensagem. É aqui que o problema de histórico aparece — e é o teste que a maioria pula.
  3. Peça uma ação real de ferramenta: "liste os arquivos do projeto X" e depois "leia o arquivo Y e me diga o que ele faz". Verifique se ele executou, e não apenas descreveu o que faria.

Checklist final

  • Versão do Claude Code igual ou superior a 2.1.258.
  • Segundo turno respondendo na mesma sessão.
  • Ferramenta executando de verdade (não só no texto).
  • Bot restrito ao seu usuário.
  • Cadeia de fallback aparecendo no fallback list.

O que esperar depois

Com o agente de pé, o ganho não é "escrever código mais rápido": é delegar tarefas inteiras — ler um repositório e apontar o que quebra em produção, subir uma aplicação de teste, escrever os testes que faltam, revisar um pull request. Você deixa de usar o agente como autocomplete e passa a usá-lo como um segundo par de mãos, com memória do que já foi feito.

O detalhe que faz diferença no dia a dia é a etapa 6. Um agente que responde bonito mas não executa ferramenta é indistinguível de um chatbot — e é justamente por isso que o teste de dois turnos com uma ação real vale mais que qualquer demonstração de texto.