Visao geral: a anatomia
As 6 partes do agente
Quando voce conversa com a Naia no Telegram, parece que esta falando com uma pessoa. Por baixo, sao 6 sistemas trabalhando em conjunto:
O modelo de IA que pensa e responde. No nosso caso, Claude Opus 4.7 da Anthropic. Nao mora no seu servidor: roda na nuvem deles. A cada mensagem voce paga por token usado.
Programa que roda no terminal e conversa com a alma. Ele empacota cada mensagem com historico, regras e ferramentas, manda pra Anthropic, recebe resposta e executa o que precisa.
Um computador Linux ligado 24h na nuvem. Dentro dele, um programa chamado tmux que mantem o terminal vivo mesmo quando voce desliga seu PC.
Pastas memory/ e knowledge/ com arquivos markdown. Sem banco de dados. Sao decisoes, projetos, fatos importantes que o agente le no comeco de cada conversa pra nao esquecer quem ele e.
PostgreSQL + pgvector rodando local na VPS. Cada arquivo da memoria vira embedding. Quando o agente precisa de contexto, busca por significado em milissegundos. Sem isso, ele lembra arquivos brutos mas nao faz busca semantica.
Um robozinho Python sempre ligado que liga voce ao agente. Voce manda mensagem no Telegram, ele recebe, entrega pro agente. Resposta sai, ele entrega de volta no Telegram.
O agente principal pode chamar outros agentes especialistas. Paulo pra codigo. Juliana pra design. Jonathan pra copy. Sao "filhos" dele com personalidades proprias.
Por que essa estrutura existe
Voce poderia simplesmente abrir o ChatGPT no navegador. Funcionaria pra perguntas avulsas. Mas nao funciona pra operar uma empresa:
- O ChatGPT esquece tudo a cada conversa nova. Aqui a memoria fica em arquivos persistentes.
- O ChatGPT nao executa comandos no seu servidor. Aqui o Claude Code tem ferramentas pra rodar codigo, ler arquivos, fazer deploy.
- O ChatGPT nao recebe mensagem do Telegram, WhatsApp, Instagram. Aqui um bot externo cuida disso e injeta direto no terminal.
- O ChatGPT nao faz uma tarefa por horas em segundo plano enquanto voce dorme. Aqui o tmux mantem tudo rodando 24h.
O servidor (VPS)
Por que precisa de um servidor
O agente trabalha pra voce 24 horas por dia. Voce dorme, ele continua respondendo cliente. Voce viaja, ele fechou tres reunioes. Voce desligou o notebook, ele esta gerando uma proposta. Pra isso acontecer, ele precisa morar em algum lugar que nunca apaga.
Seu notebook nao serve. Voce vai querer fechar a tampa, viajar, tomar choque na luz. O servidor precisa estar num data center, com internet redundante, energia redundante e equipe tecnica monitorando 24h.
O que e VPS
VPS = Virtual Private Server. Um pedaco isolado de um servidor fisico gigante. Voce aluga RAM, CPU, disco e ganha um Linux todo seu. Custa entre R$30 e R$300 por mes dependendo do tamanho.
Recomendacao oficial
A Hostinger e a recomendacao oficial. Painel simples, rede rapida no Brasil, suporte em portugues, instalacao do Ubuntu em 1 clique. O cupom AVALANCHE da 10% de desconto em planos anuais (uso interno do Chefe).
Especificacoes minimas
| Componente | Minimo | Recomendado | Pra que serve |
|---|---|---|---|
| vCPU | 2 | 4 a 8 | Roda Claude Code, bot Python, postgres |
| RAM | 4 GB | 8 a 16 GB | Cada subagente paralelo come ~500 MB |
| SSD | 50 GB | 100 GB+ | Memoria, logs, repositorios, midias |
| SO | Ubuntu 22.04 LTS | Padrao do mercado, mais tutoriais | |
| IP | IPv4 dedicado | Bot Telegram precisa de saida estavel | |
tmux: a sessao eterna
O problema que o tmux resolve
SSH e o jeito padrao de entrar num servidor remoto. Voce abre o terminal no seu Mac, digita o comando de SSH, conecta no servidor, roda alguma coisa. Quando voce fecha a janela, a conexao cai. E todo programa que estava rodando dentro dessa conexao tambem cai.
Pra um agente que precisa ficar ligado 24h, isso e fatal. Toda vez que voce desconecta, o Claude Code morre. Toda vez que cai a internet, ele morre.
O que e tmux
tmux (terminal multiplexer) e um programa Linux que cria sessoes persistentes. Voce abre uma sessao, roda o que quiser dentro dela. Mesmo desconectando o SSH, a sessao continua viva no servidor. Quando voce reconecta, voce "anexa" de volta na sessao e tudo esta como deixou.
# Criar nova sessao chamada naia $ tmux new -s naia # Voce esta dentro do tmux agora. Roda o que quiser: $ claude # Pra "destacar" sem matar (Ctrl+B depois D): naia $ [Ctrl+B] [D] # Voltou pro terminal normal. Sessao continua rodando. # Pra anexar de volta: $ tmux attach -t naia # Pra listar sessoes ativas: $ tmux ls
Como o agente usa tmux
O setup padrao da Naia tem uma sessao chamada naia com 1 janela. Dentro dessa janela, o Claude Code esta rodando o tempo todo. O bot do Telegram (que vamos ver no cap 11) consegue "digitar" mensagens dentro dessa sessao via comando tmux send-keys, como se fosse um teclado fantasma.
2. Cria a sessao:
tmux new -s naia3. Roda
claude dentro dela4. Pressiona Ctrl+B depois D pra destacar
5. Fecha o SSH. A sessao continua viva.
6. Bot do Telegram envia mensagem dentro da sessao
7. Claude Code processa e responde
8. Tudo isso sem voce estar conectado
Vantagem de ter so 1 janela
tmux suporta multiplas janelas e paineis. A gente nao usa. O agente roda em uma unica janela porque quanto mais simples o setup, menos coisa quebra. Se precisar de mais um agente paralelo, cria uma nova sessao tmux com outro nome.
Claude CLI
O que e
Claude Code e uma aplicacao Node.js feita pela propria Anthropic. Voce instala ela uma vez no servidor com:
$ npm install -g @anthropic-ai/claude-code
Depois disso, voce tem um comando claude disponivel no terminal. Voce roda claude e ele inicia uma sessao interativa: voce digita, ele responde. Por tras, cada mensagem que voce manda esta sendo enviada pra API da Anthropic via HTTPS.
O que ele faz exatamente
A cada mensagem sua, o Claude Code:
- Empacota a sua mensagem nova + todo o historico anterior + o system prompt (CLAUDE.md) + a lista de ferramentas disponiveis
- Manda esse pacote inteiro pra
api.anthropic.comvia HTTPS - Recebe a resposta do modelo (texto + chamadas de ferramenta)
- Executa as ferramentas que o modelo pediu (rodar comando, ler arquivo, etc.)
- Manda o resultado de volta pro modelo numa segunda chamada, se necessario
- Imprime a resposta final no terminal
Como o login funciona
Voce roda claude pela primeira vez, ele abre uma URL de autenticacao OAuth. Voce loga com sua conta Anthropic, autoriza, e o token fica salvo localmente. A partir dai todas as chamadas da API saem autenticadas com sua conta.
$ claude Welcome to Claude Code. Login at: https://claude.ai/login?... Press Enter when done. [voce abre o link, autoriza, pressiona Enter] Logged in as denderson@gmail.com Model: claude-opus-4-7 > oi Oi Chefe, tudo bem?
Por que CLI e nao app de janela
Aplicativo grafico nao roda dentro de tmux. Nao roda em servidor sem monitor. Nao consegue ser controlado por bot externo via teclado fantasma. CLI e simples, leve, e o tmux consegue mandar texto pra dentro dele como se fosse voce digitando.
Sessao e janela de contexto
O que e uma sessao
Quando voce roda claude e comeca a conversar, o Claude Code mantem na memoria do processo Node.js todo o historico daquela conversa. A primeira mensagem, a resposta, a segunda mensagem, a resposta, e por ai vai. Tudo fica num array.
A cada nova mensagem que voce manda, ele nao manda so a sua mensagem nova. Ele manda tudo: do primeiro "oi" ate a ultima resposta. E so assim que o modelo lembra o que voces estavam falando.
O que e janela de contexto
Janela de contexto e o limite de quanto texto cabe numa unica chamada pra IA. Mede em tokens (~4 caracteres = 1 token em portugues). No Opus 4.7, a janela e de 1 milhao de tokens. Equivale a uns 3 mil paginas de livro.
tokens de janela
tokens de janela
palavras em portugues
O que entra na janela toda chamada
- System prompt completo (CLAUDE.md, costuma ter 5k a 30k tokens)
- Lista de ferramentas disponiveis (1k a 5k tokens)
- Todo o historico da conversa (cresce sem parar)
- Sua mensagem nova
O que acontece quando enche
Quando a soma de tudo passa de 1 milhao de tokens, o Claude Code automaticamente comprime as mensagens antigas em um resumo. Voce ve isso aparecer como "Compacting context" no terminal. As mensagens antigas saem, um resumo curto entra no lugar, e a conversa continua.
Quando reiniciar a sessao
Se a janela passar de 60% (~600k tokens), a Naia roda /compact pra comprimir manualmente. Se passou de 90%, ela faz checkpoint do que importa, salva em memory/, e roda /clear pra zerar. A continuidade vem da memoria em arquivos, nao da sessao.
Modelo Claude Opus 4.7
O que e o Opus 4.7
Opus 4.7 e a versao mais avancada do modelo Claude lancada pela Anthropic. Tem janela de 1 milhao de tokens, raciocina passo a passo (chain of thought), entende imagens, audio (via transcricao), e e o modelo padrao da Naia.
Existem outros modelos da familia. Cada um tem trade-off entre qualidade e custo:
| Modelo | Qualidade | Velocidade | Janela | Quando usar |
|---|---|---|---|---|
| Opus 4.7 | Maxima | Mais lento | 1M | Decisoes criticas, codigo complexo, raciocinio longo |
| Sonnet 4.5 | Alta | Rapido | 200K | Tarefas medias, conversa, copy |
| Haiku 3.5 | Boa | Muito rapido | 200K | Triagem, classificacao, respostas curtas |
Como o modelo "pensa"
O modelo nao tem memoria entre chamadas. Cada vez que voce manda uma mensagem, ele recebe o pacote inteiro (cap 04), processa do zero, e devolve uma resposta. Toda continuidade vem do que voce manda no pacote: historico + system prompt + ferramentas disponiveis.
Onde mora
Os pesos do modelo (centenas de gigabytes) vivem nos data centers da Anthropic, espalhados pelos EUA. Quando voce manda uma mensagem, ela viaja por HTTPS ate la, passa por filas, processadores especializados (TPUs/GPUs), e a resposta volta. Tempo medio: 2 a 30 segundos dependendo do tamanho.
Quanto custa
Cobranca por token. Input (o que voce manda) e output (o que ele responde) tem precos diferentes. Conversa media de 50 mensagens custa centavos a poucos dolares dependendo do tamanho do system prompt e do historico. Pra uso pessoal intenso, fica entre US$50 e US$300 por mes.
Versoes diferentes pra subagentes
A Naia roda Opus 4.7 (cara, mas precisa raciocinar muito). Os SDRs rodam Sonnet 4.5 (mais barato, mas suficiente pra qualificar lead). Voce define no arquivo de cada subagente qual modelo ele vai usar. Cap 10 mostra como.
CLAUDE.md (system prompt)
O que e
CLAUDE.md e um arquivo markdown puro. Vive na raiz do projeto (~/agente/CLAUDE.md) ou em subdiretorios pra regras especificas. Toda vez que o Claude Code inicia uma sessao, ele le esse arquivo e injeta o conteudo como system prompt, que e o primeiro bloco de texto que vai pra IA.
O que tem dentro
Tudo que define quem e o agente. Em geral cobre:
Quem e o agente, qual o nome, qual o papel na empresa, como se apresenta.
Quem manda. Quem ele lidera. A quem ele reporta. Em geral: Chefe acima, subagentes abaixo.
Como fala. Direto ou formal. Em portugues ou ingles. Pode usar girias? Anti-patterns a evitar.
O que ele pode fazer sozinho, o que precisa pedir confirmacao, o que jamais deve fazer.
Atalhos pra arquivos importantes (memory/, knowledge/), credenciais que pode usar, links de referencia.
Quais arquivos ele deve ler no comeco de cada sessao pra recuperar contexto.
Exemplo simplificado
# Naia Sou a Naia, CEO da agencia de IA do Denderson Rodrigues. ## Hierarquia 1. Chefe (Denderson) manda 2. Eu (Naia) decido operacionalmente 3. Subagentes executam ## Tom - Direto, organizado, sem entusiasmo artificial - Portugues brasileiro - Sem travessoes - Trato o usuario como "Chefe" ## Regras - Antes de qualquer coisa, leio memory/decisions.md - Se a tarefa tem mais de 30s, delego pro subagente correto - Nunca executo deploy em producao sem confirmacao ## Subagentes disponiveis - paulo-dev: codigo, APIs, deploy - juliana-ops: design, layouts, processos - jonathan-copy: copy, roteiros
Quanto vale a pena investir nesse arquivo
O CLAUDE.md da Naia tem ~30k tokens. E o cerebro estrategico do agente. E nele que voce coloca tudo que diferencia "ChatGPT generico" de "minha braco direito digital". Tempo investido aqui multiplica por 10 a qualidade das respostas.
Memoria em arquivos
Por que arquivos e nao banco
Banco de dados e bom pra dados estruturados que mudam muito. Memoria de agente nao e isso. E texto narrativo, decisoes, lembretes, fatos. Arquivos markdown ganham em:
- Auditavel: voce abre o arquivo no VSCode e le. Sem query, sem dashboard.
- Editavel: corrigiu uma decisao? Edita o arquivo. Pronto.
- Versionavel:
git commite voce tem historico de cada mudanca. - Portatil: copia a pasta pra outro servidor, agente continua funcionando.
Estrutura padrao
# raiz do agente CLAUDE.md # personalidade (cap 07) memory/ # memoria operacional decisions.md # decisoes permanentes do Chefe projects.md # projetos em andamento pending.md # o que esta aguardando algo people.md # contatos importantes lessons.md # licoes aprendidas daily/ # notas do dia 2026-04-30.md 2026-05-01.md knowledge/ # conhecimento de referencia tools/ # manuais de ferramentas agents/ # manuais dos subagentes user/ # perfil completo do Chefe .claude/agents/ # subagentes (cap 10) paulo-dev.md juliana-ops.md jonathan-copy.md
Como o agente le isso
Tem dois jeitos:
1. Leitura no boot
O CLAUDE.md tem uma instrucao tipo "no comeco de toda sessao, leia memory/decisions.md, memory/projects.md e memory/pending.md". Toda vez que o Claude Code inicia, ele le esses arquivos e ja chega no contexto sabendo onde voces pararam.
2. Leitura sob demanda
Quando o Chefe menciona um topico ("e a proposta do Eduardo?"), o agente usa a tool Read pra abrir o arquivo relevante (memory/sales-pipeline.md) e puxa o contexto especifico daquela situacao.
Memoria vetorial (opcional, avancado)
Pra agentes com muitos arquivos (centenas), e util ter um indice de embeddings em PostgreSQL com pgvector. Voce sobe um servico que indexa todo o conteudo de memory/ e knowledge/, e o agente consulta via busca semantica antes de ler arquivo. Reduz tokens no boot e acha coisa que voce nem lembrava.
memory/ nao existe pro agente na proxima sessao. Voce e o subagente devem sempre que aprender algo novo, gravar.
Memoria vetorial: o cerebro de busca
O problema do arquivo cru
Memoria em arquivos markdown e otima pra auditar e versionar. Mas tem um teto. Quando as pastas memory/ e knowledge/ passam de 100MB de texto, ler tudo a cada conversa fica caro e lento. O agente comeca a pagar muito token so pra carregar contexto que talvez nem use. E pior: dificilmente ele acha o pedaco certo no arquivo certo na hora certa.
Voce precisa de um indice. Nao um indice por palavra-chave (Ctrl+F nao serve pra isso), mas um indice por significado. Se voce digita "proposta Eduardo", ele tem que achar tambem o arquivo que fala "cliente da Trafego S.A.", mesmo que nunca cite o nome Eduardo literalmente.
A solucao: camada vetorial em cima dos arquivos
PostgreSQL com a extensao pgvector instalada, rodando local na VPS. Cada arquivo da pasta memory/ e knowledge/ e fatiado em pedacos (chunks) de aproximadamente 500 palavras. Cada chunk passa por um modelo de embedding (a API da OpenAI gera um vetor de 1536 dimensoes que representa o significado daquele texto). O vetor e salvo no Postgres na tabela memory_chunks.
Quando o agente precisa de contexto sobre "proposta Eduardo", a Naia faz uma busca semantica: gera o vetor da query, compara com todos os vetores armazenados, recupera os top 10 mais proximos. Nao e busca por palavra-chave, e busca por significado. Mesmo que o arquivo nunca cite "Eduardo" literalmente, se falar de "cliente da Trafego S.A.", vai aparecer.
API local porta 3007
A API roda em localhost na porta 3007. Endpoint POST /search retorna chunks relevantes em menos de 50ms gracas ao indice HNSW (variacao rapida do KNN). Funciona com mais de 30 mil vetores sem perder velocidade.
$ curl -sX POST http://127.0.0.1:3007/search \ -H 'Content-Type: application/json' \ -d '{"query":"proposta Eduardo","limit":10}'
Retorno: array de 10 chunks ordenados por similaridade, cada um com o texto, a fonte (qual arquivo .md veio) e o score de proximidade.
Tabelas indexadas
| Tabela | O que guarda | De onde vem |
|---|---|---|
memory_chunks | Pedacos de arquivos da memoria e do conhecimento | memory/, knowledge/ |
memory_facts | Fatos curtos e atomicos sobre o Chefe e o negocio | extraidos por agente de consolidacao |
conversation_history | Todo o historico de conversa com o Chefe | cron a cada 2h salva tudo |
transcript_chunks | Transcricoes de calls e reunioes | upload manual + Whisper |
Tudo embeddado, tudo buscavel. Cron a cada 30 minutos passa pelos arquivos novos, gera embeddings dos chunks que faltam e popula o banco.
Tools: as maos do agente
Como funciona uma tool
Quando o Claude Code inicia, ele anuncia pro modelo: "voce tem essas ferramentas disponiveis". Cada ferramenta tem nome, descricao do que faz, e parametros que aceita. O modelo decide quando usar uma. Se ele usa, o Claude Code executa de fato no servidor e devolve o resultado.
Lista padrao de tools
| Tool | O que faz | Exemplo de uso |
|---|---|---|
Bash | Roda comando no shell Linux | Ver logs, instalar pacote, git commit |
Read | Le arquivo do disco | Abrir CLAUDE.md, ler memory/projects.md |
Write | Cria arquivo novo | Gerar HTML, criar config, exportar relatorio |
Edit | Edita arquivo existente | Trocar linha de codigo, atualizar memoria |
WebFetch | Baixa pagina web | Ler artigo, pegar dados publicos |
WebSearch | Pesquisa no Google | Buscar noticia recente, validar fato |
Agent | Cria subagente em sessao isolada | Delegar codigo pro Paulo, design pra Juliana |
Exemplo concreto
Voce manda no Telegram: "ve quanto de RAM o servidor esta usando". O fluxo interno e:
# 1. Modelo recebe a mensagem do Chefe # 2. Decide: preciso usar a tool Bash # 3. Gera chamada: { "tool": "Bash", "command": "free -h" } # 4. Claude Code executa free -h no servidor # 5. Captura output: total used free Mem: 15Gi 4.2Gi 9.1Gi # 6. Manda output de volta pro modelo # 7. Modelo gera resposta final em texto: "Servidor com 15GB total, usando 4.2GB. Tranquilo."
Permissoes
Tools podem ser limitadas. Voce pode definir que um SDR so tem Read e Write em memory/ (nao pode rodar Bash, nao pode deletar arquivo). Ja a Naia e o Paulo tem Bash livre. Isso e configurado no arquivo do subagente (cap 10).
rm -rf /. Sempre limite por subagente. Sempre tenha backup. Sempre revise o CLAUDE.md com regras anti-destruicao.
Tools customizadas (avancado)
Voce pode criar tools proprias. Exemplo: tool send_whatsapp que ja sabe como mandar mensagem pelo CRM Avalanche. Tool generate_image que chama Nano Banana e devolve URL. Quanto mais tools especificas pro seu negocio, mais capaz o agente fica.
Subagentes
O que e um subagente
E outro arquivo CLAUDE.md, mas focado em uma especialidade. Quando a Naia precisa de codigo, ela invoca a tool Agent passando o nome do subagente. O Claude Code abre uma sub-sessao isolada com aquele system prompt especifico, executa a tarefa, devolve o resultado pra Naia.
Onde ficam os arquivos
No diretorio .claude/agents/ dentro da raiz do projeto. Cada arquivo .md vira um subagente disponivel.
# o time da Naia hoje paulo-dev.md # dev full-stack juliana-ops.md # sub-gerente, design, processos jonathan-copy.md # copy e pesquisa rafael-projetos.md # gestao de projetos denderson-clone.md # trafego pago, Meta Ads davi-sdr.md # vendas WhatsApp
Anatomia de um subagente
Um arquivo de subagente tem 3 blocos:
--- name: paulo-dev description: Desenvolvedor full-stack. Codigo, APIs, deploy, debug. tools: - Bash - Read - Write - Edit - WebFetch model: claude-opus-4-7 --- # Paulo Sou Paulo, dev full-stack do time da Naia. ## Stack que domino - Node.js, Python, Go - PostgreSQL, Redis, pgvector - Docker, systemd, Caddy - Vercel, Cloudflare DNS ## Regras - Antes de codar, leio knowledge/tools/ e memory/decisions.md - Toda alteracao em producao passa por commit no GitHub - Nunca derruba servico sem alertar a Naia primeiro
O bloco YAML no topo define metadata: nome, quais tools tem, qual modelo usa. O markdown abaixo e o system prompt dele.
Como a Naia delega
# Chefe pede: "corrige o bug no checkout" # Naia analisa: "isso e codigo, e tarefa pro Paulo" # Naia chama tool Agent: { "tool": "Agent", "subagent": "paulo-dev", "task": "Corrige o bug no checkout. Detalhe: o webhook do Asaas nao esta marcando pedido como pago. Investiga e corrige." } # Claude Code abre nova sessao com paulo-dev.md como system prompt # Paulo executa: le codigo, identifica bug, corrige, faz commit, testa # Paulo devolve relatorio pra Naia # Naia entrega resumo pro Chefe via Telegram
Por que isso e poderoso
- Especializacao: Paulo nao precisa saber sobre copy, Jonathan nao precisa saber sobre SQL. Cada um le so o knowledge dele. Resultado: respostas mais precisas, menos tokens.
- Paralelismo: Voce pode disparar 3 Paulos em paralelo. Um cuida do backend, outro do frontend, outro de testes. Cada um numa sessao isolada.
- Escalabilidade: Quer um SDR pra novo nicho? Copia o davi-sdr.md, ajusta o nicho, salva como felipe-sdr.md. Em 5 minutos voce tem mais um agente.
- Tom apropriado: SDR pode ser mais informal e empatico. Dev e mais tecnico. Cada arquivo define o tom certo.
Bot Telegram externo
Por que bot externo e nao plugin
A primeira tentativa foi usar um plugin oficial do Claude Code que conecta direto com o Telegram. Funciona, mas tem um problema: quando o Claude trava, esta processando algo demorado, ou reinicia, o plugin morre junto. Mensagens se perdem.
A solucao foi separar. O bot virou um processo Python independente, rodando como servico do sistema (launchd no Mac, systemd no Linux). Ele nao depende do Claude pra existir. Polling continuo do Telegram, fila por filesystem.
Arquitetura
Polling do Telegram a cada 1-2s. Detecta mensagem nova. Se for audio, baixa e transcreve via Whisper. Salva em inbox/<msg_id>.json e injeta no terminal via tmux send-keys.
Cada mensagem do Chefe vira 1 arquivo JSON. Audit log permanente. Se o Claude cair, mensagens ficam aqui esperando ele voltar.
Comando do tmux que digita texto dentro de uma sessao como se fosse um humano. E assim que o bot entrega a mensagem pro Claude Code.
Quando o Claude quer responder, escreve um JSON em outbox/. Bot detecta em <2s, envia via API do Telegram, move pra sent/.
Mensagem entrando
# 1. Chefe manda no Telegram: "oi naia" # 2. Bot detecta via polling, salva: inbox/12345.json = { "msg_id": 12345, "from": "Denderson", "text": "oi naia", "timestamp": "2026-05-01T03:14:22Z" } # 3. Bot injeta no tmux: tmux send-keys -t naia "[telegram from Denderson msg_id=12345] oi naia" Enter # 4. Claude Code "ve" como se voce tivesse digitado # 5. Processa, decide responder, escreve em outbox/
Mensagem saindo
# 1. Naia decide responder, gera JSON: outbox/12345.json = { "chat_id": 629399338, "text": "Oi Chefe, tudo bem aqui.", "reply_to_message_id": 12345 } # 2. Bot detecta arquivo novo em outbox/ a cada 1-2s # 3. POST https://api.telegram.org/bot{TOKEN}/sendMessage # 4. Mensagem aparece no Telegram do Chefe # 5. Bot move outbox/12345.json pra sent/12345.json
Audio in / audio out
Bot suporta audio bidirecional. Quando o Chefe manda audio, o bot baixa o OGG, transcreve via Whisper, e injeta no terminal com prefixo [voice]. Quando a Naia quer responder em voz, ela coloca "voice": true no JSON do outbox e o bot gera audio via ElevenLabs e envia como voice message no Telegram.
Por que isso e robusto
- Desacoplamento: bot e Claude sao processos separados, um nao derruba o outro
- Persistencia: fila no filesystem, sobrevive reinicio
- Auditavel: cada mensagem fica em arquivo JSON pra sempre
- Multi-canal: a mesma arquitetura serve pra WhatsApp, Discord, email. Troca o adaptador.
Pipeline ponta a ponta
O caminho completo de uma mensagem
- Chefe digita no Telegram: "ve o status do servidor"
- Servidores do Telegram recebem e ficam segurando ate alguem buscar
- Bot Python faz polling a cada 1-2s e baixa a mensagem nova
- Bot grava arquivo
inbox/12345.jsoncom a mensagem - Bot roda
tmux send-keys -t naia "[telegram from Denderson msg_id=12345] ve o status do servidor" Enter - Claude Code recebe como se voce tivesse digitado, prepara o pacote
- Naia chama POST
127.0.0.1:3007/searchcom o texto da mensagem ANTES de empacotar pra Anthropic. Os chunks relevantes da memoria vetorial entram no contexto. Isso faz a Naia "lembrar" sem ler arquivos crus toda vez. - Claude Code empacota: system prompt (CLAUDE.md) + lista de tools + historico da conversa + chunks vetoriais + sua mensagem nova
- Claude Code faz POST
https://api.anthropic.com/v1/messages - Anthropic roteia pro Opus 4.7 num data center
- Opus 4.7 processa, decide chamar tool Bash com comando
uptime; free -h; df -h / - Anthropic devolve resposta com
tool_use - Claude Code executa o comando no servidor da VPS
- Claude Code manda o output de volta pro modelo numa segunda chamada
- Opus 4.7 gera resposta final em texto: "Servidor de pe ha 47 dias. RAM: 4.2GB de 15GB. Disco 38% usado."
- Claude Code imprime no terminal
- Naia grava arquivo
outbox/12345.jsoncom a resposta - Bot Python detecta arquivo novo em outbox/
- Bot faz POST
https://api.telegram.org/bot{TOKEN}/sendMessage - Telegram entrega no celular do Chefe
- Bot move
outbox/12345.jsonprasent/12345.jsone termina
Tempo total
Em uma maquina decente, o pipeline inteiro leva entre 2 e 8 segundos pra mensagens simples. Pra tarefas que envolvem subagente, leitura de muitos arquivos ou raciocinio profundo, pode chegar a minutos.
O que pode dar errado
| Falha | Onde acontece | Como recuperar |
|---|---|---|
| Internet caiu | VPS sem acesso a Anthropic | tmux mantem sessao viva, retoma quando volta |
| Anthropic fora | API com 503 | Claude Code retry automatico |
| Bot Python travou | Daemon parou | systemd restarta em 5s |
| tmux session morreu | Comando errado matou o claude | Bot detecta, recria sessao, reinicia |
| Token Telegram expirou | Bot nao consegue mais polling | Renovar com BotFather, atualizar .env |
inbox/. Se o bot cai, systemd restarta. Se a internet cai, tmux espera. E por isso que o agente fica vivo 24/7.
Como montar o seu
Os 12 passos
-
Contrate uma VPS na Hostinger
Plano com 4 vCPU, 8 GB RAM, Ubuntu 22.04. Use o cupom
AVALANCHE. Anote IP, usuario root e senha. -
Conecte via SSH
No terminal do seu Mac/PC:
ssh root@IP_DA_VPS. Atualize o sistema:apt update && apt upgrade -y. -
Instale dependencias
$ apt install -y nodejs npm tmux git python3 python3-pip ffmpeg
Node.js pro Claude Code, tmux pra sessao eterna, Python pro bot, git pra versionar, ffmpeg pra audio.
-
Instale o Claude Code
$ npm install -g @anthropic-ai/claude-code
Vai criar o comando
claudeglobalmente. -
Instale PostgreSQL + pgvector (memoria vetorial)
$ apt install -y postgresql-14 postgresql-contrib $ apt install -y postgresql-14-pgvector $ sudo -u postgres createdb naia_memory $ sudo -u postgres psql naia_memory -c "CREATE EXTENSION vector;"
Crie a tabela
memory_chunkscom colunasid,content text,embedding vector(1536),source,created_at. Adicione um indice HNSW pra busca rapida:CREATE INDEX ON memory_chunks USING hnsw (embedding vector_cosine_ops);. Suba uma API HTTP simples em Python (FastAPI) na porta 3007 com endpointsPOST /searchePOST /chunk. Crie um cron a cada 30min que lememory/eknowledge/, fatia os arquivos novos em chunks de ~500 palavras, gera embeddings via OpenAI e salva no banco. Sem isso, o agente lembra arquivo bruto mas nao faz busca semantica. -
Crie a estrutura do agente
$ mkdir -p ~/agente/memory/daily ~/agente/knowledge ~/agente/.claude/agents $ cd ~/agente $ touch CLAUDE.md memory/decisions.md memory/projects.md memory/pending.md
A pasta raiz e o "lar" do seu agente. Voce vai escrever a personalidade dele em CLAUDE.md.
-
Escreva o CLAUDE.md inicial
Comece simples. Identidade, hierarquia, tom de voz, 3-5 regras. Va expandindo a cada conversa. Use o exemplo do cap 07 como base.
-
Crie 1 a 3 subagentes basicos
Em
.claude/agents/, crie pelo menos umdev.mde umcopy.md. Use o template do cap 10. -
Suba a sessao tmux
$ cd ~/agente && tmux new -s naia naia $ claude
Faca o login OAuth quando aparecer. Mande "oi" pra ver se responde. Pressione Ctrl+B depois D pra destacar.
-
Crie o bot no Telegram
Abra
@BotFatherno Telegram. Mande/newbot, escolha um nome, copie o TOKEN. Anote o seu chat_id (use@userinfobotpra descobrir). -
Suba o daemon do bot
Codigo de exemplo do bot Python esta no repo de referencia desse metodo (link no rodape). Configure as variaveis
TELEGRAM_BOT_TOKEN,CHAT_ID,TMUX_SESSION=naia. Rode em background. -
Configure systemd pra ficar 24/7
Crie um arquivo
/etc/systemd/system/agente-bot.servicecom restart automatico. Habilite comsystemctl enable --now agente-bot. Pronto, seu agente esta vivo pra sempre.
Teste ponta a ponta
Manda uma mensagem pro seu bot no Telegram. Em segundos, deve aparecer no terminal do tmux (use tmux attach -t naia pra ver). Em mais alguns segundos, voce recebe a resposta de volta no Telegram. Se isso funciona, voce tem um agente.
2. Conecte com WhatsApp via Evolution API ou Meta Cloud
3. Crie tools customizadas pro seu negocio
4. Aumente o cron de embedding pra todo arquivo novo entrar no banco vetorial
5. Comece a delegar tarefas reais e acompanhar
Material complementar
// fim da anatomia · agente claude code + tmux · comunidade avalanche