AVALANCHE BIOS v6.1.0 · (c) DENDERSON SYSTEMS 2026
Booting agent anatomy decoder ...... OK
Loading modelo: claude-opus-4-7 ..... OK
Mounting tmux session: naia ......... OK
Connecting Telegram bot daemon ...... OK
Loading 14 capitulos ................ OK
 
[SYSTEM READY] press any key to continue
naia@avalanche:~/anatomia/cap-01.md_
// CAP 01

Visao geral: a anatomia

Antes de instalar nada, e preciso entender. Um agente de IA nao e um software unico. E a soma de 6 partes que precisam estar conectadas o tempo todo. Esse capitulo apresenta cada peca antes da gente detalhar uma a uma nos capitulos seguintes.
Anatomia do agente: 6 pecas conectadas

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:

Parte 1
ALMA / o cerebro

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.

Parte 2
CORPO / Claude Code

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.

Parte 3
CASA / VPS + tmux

Um computador Linux ligado 24h na nuvem. Dentro dele, um programa chamado tmux que mantem o terminal vivo mesmo quando voce desliga seu PC.

Parte 4
MEMORIA EM ARQUIVO / pastas .md

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.

Parte 5
MEMORIA VETORIAL / busca semantica

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.

Parte 6
CANAL / bot Telegram externo

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.

Bonus
SUBAGENTES

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.
A METAFORA QUE FECHA
Pense em um funcionario contratado. Ele tem um cerebro (alma). Tem um corpo pra executar tarefas (corpo). Tem uma sala pra trabalhar (casa). Tem cadernos com anotacoes (memoria em arquivo). Tem um indice mental que acha qualquer assunto em segundos (memoria vetorial). Tem um celular pra falar com voce (canal). E pode ligar pra outros colegas especialistas quando precisa (subagentes). E exatamente isso que vamos montar nos proximos capitulos.
// CAP 02

O servidor (VPS)

Tudo comeca numa maquina sempre ligada. Linux Ubuntu, IP fixo, energia e internet 24h. E onde os arquivos da personalidade, memorias e ferramentas vivem. Sem servidor, nao tem agente.
Servidor VPS Hostinger

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

VPS recomendada pelo chefe
Hostinger // VPS sempre ligada por baixo custo
hostinger.com.br/avalanche cupom AVALANCHE 10% off em VPS anual

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

ComponenteMinimoRecomendadoPra que serve
vCPU24 a 8Roda Claude Code, bot Python, postgres
RAM4 GB8 a 16 GBCada subagente paralelo come ~500 MB
SSD50 GB100 GB+Memoria, logs, repositorios, midias
SOUbuntu 22.04 LTSPadrao do mercado, mais tutoriais
IPIPv4 dedicadoBot Telegram precisa de saida estavel
QUANDO TROCAR DE PLANO
Comece com 4 vCPU e 8 GB. Quando voce tiver 3+ subagentes rodando em paralelo o tempo todo, sobe pra 8 vCPU e 16 GB. Nao gasta dinheiro a toa no comeco. Da pra trocar de plano sem reinstalar nada.
// CAP 03

tmux: a sessao eterna

Voce abre o terminal, roda um programa, fecha o terminal. O programa morre. tmux resolve esse problema. E o que faz o agente continuar vivo mesmo quando voce desconecta o SSH.
Sessao tmux com terminal Matrix

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.

FLUXO TIPICO
1. Voce conecta no servidor via SSH
2. Cria a sessao: tmux new -s naia
3. Roda claude dentro dela
4. 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.

// CAP 04

Claude CLI

Claude Code e o programa que voce roda no terminal pra conversar com o modelo Claude. Nao e o cerebro. E o cliente que faz a ponte entre voce e a Anthropic.
Claude CLI conectando terminal a Anthropic

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:

  1. Empacota a sua mensagem nova + todo o historico anterior + o system prompt (CLAUDE.md) + a lista de ferramentas disponiveis
  2. Manda esse pacote inteiro pra api.anthropic.com via HTTPS
  3. Recebe a resposta do modelo (texto + chamadas de ferramenta)
  4. Executa as ferramentas que o modelo pediu (rodar comando, ler arquivo, etc.)
  5. Manda o resultado de volta pro modelo numa segunda chamada, se necessario
  6. Imprime a resposta final no terminal
PONTO CRITICO PRA ENTENDER
O cerebro nao mora no seu servidor. Ele mora nos data centers da Anthropic. O Claude Code e so o cliente que conversa com ele. Voce paga por token enviado e por token recebido. Por isso a fatura cresce conforme voce conversa mais.

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.

// CAP 05

Sessao e janela de contexto

A "sessao" e o processo Node.js mantendo a conversa em memoria. A "janela de contexto" e quanto texto cabe junto numa unica chamada pra IA. Esse capitulo explica como isso afeta a qualidade e o custo.
Janela de contexto de 1 milhao de tokens

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.

Modelo atual
Opus 4.7
1M

tokens de janela

Comparacao
Sonnet 4.5
200K

tokens de janela

Equivale a
~3000 pgs
~750k

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.

CUIDADO COM O CUSTO
Janela maior = mais tokens enviados a cada chamada = mais caro. Conversa de 800k tokens custa o equivalente a um livro inteiro toda vez que voce manda uma mensagem nova. Por isso e importante resumir e arquivar conversas longas, e usar memoria em arquivos (cap 08) pra nao depender do contexto.

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.

// CAP 06

Modelo Claude Opus 4.7

O cerebro propriamente dito. Mora nos data centers da Anthropic. Voce nao instala, nao baixa, nao precisa de GPU. Cada mensagem vai pra cloud, ele processa, devolve.
Modelo 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:

ModeloQualidadeVelocidadeJanelaQuando usar
Opus 4.7MaximaMais lento1MDecisoes criticas, codigo complexo, raciocinio longo
Sonnet 4.5AltaRapido200KTarefas medias, conversa, copy
Haiku 3.5BoaMuito rapido200KTriagem, 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.

VOCE NAO BAIXA O MODELO
Diferente do que muita gente pensa, voce nao precisa de GPU no seu servidor. O modelo nao roda local. Sua VPS so precisa de internet boa pra mandar e receber pacotes. CPU basica resolve.

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.

// CAP 07

CLAUDE.md (system prompt)

Sem personalidade, o Claude e generico, polido, chato. CLAUDE.md e o arquivo que injeta alma. Quem o agente e, como fala, com quem se reporta, o que pode ou nao fazer.
Arquivo CLAUDE.md projetando persona

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:

Identidade

Quem e o agente, qual o nome, qual o papel na empresa, como se apresenta.

Hierarquia

Quem manda. Quem ele lidera. A quem ele reporta. Em geral: Chefe acima, subagentes abaixo.

Tom de voz

Como fala. Direto ou formal. Em portugues ou ingles. Pode usar girias? Anti-patterns a evitar.

Regras de operacao

O que ele pode fazer sozinho, o que precisa pedir confirmacao, o que jamais deve fazer.

Conhecimento essencial

Atalhos pra arquivos importantes (memory/, knowledge/), credenciais que pode usar, links de referencia.

Memoria

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.

DICA QUE FUNCIONA
Comece com 50 linhas. A cada erro do agente, volte no CLAUDE.md e adicione a regra que evitaria aquele erro. Em 2 semanas voce tem um arquivo cirurgico que reflete exatamente como sua operacao trabalha.
// CAP 08

Memoria em arquivos

Sem banco de dados. Sem ORM. Sem schema. So pastas com arquivos markdown puros. Voce pode abrir no editor, ler, editar a mao. Essa e a memoria persistente do agente.
Wall of glowing markdown files

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 commit e 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.

REGRA DE OURO
Se importa, escreve em arquivo. O que nao esta escrito em memory/ nao existe pro agente na proxima sessao. Voce e o subagente devem sempre que aprender algo novo, gravar.
// CAP 09

Memoria vetorial: o cerebro de busca

Arquivos puros sao otimos pra guardar memoria, mas nao conseguem responder "me lembra tudo que falamos sobre a proposta do Eduardo" em milissegundos. Esse capitulo explica a camada vetorial que vive em cima dos arquivos: PostgreSQL + pgvector + busca por significado.
PostgreSQL + pgvector: busca semantica como cerebro do agente

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

TabelaO que guardaDe onde vem
memory_chunksPedacos de arquivos da memoria e do conhecimentomemory/, knowledge/
memory_factsFatos curtos e atomicos sobre o Chefe e o negocioextraidos por agente de consolidacao
conversation_historyTodo o historico de conversa com o Chefecron a cada 2h salva tudo
transcript_chunksTranscricoes de calls e reunioesupload 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.

RESUMINDO
Arquivos = memoria de longo prazo crua. pgvector = mecanismo de busca que devolve so os pedacos relevantes na hora. Sem essa camada, o agente le tudo (caro) ou esquece (ruim). Com ela, le so o que importa, em qualquer volume. Esse e o pulo do gato pra escalar a memoria sem explodir o custo de tokens.
// CAP 10

Tools: as maos do agente

Modelo sozinho so gera texto. Nao executa nada. Pra fazer coisa real, ele precisa de ferramentas. Tools sao funcoes que o Claude Code expoe pro modelo: rodar comando, ler arquivo, fazer requisicao web.
Agente com multiplos bracos roboticos

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

ToolO que fazExemplo de uso
BashRoda comando no shell LinuxVer logs, instalar pacote, git commit
ReadLe arquivo do discoAbrir CLAUDE.md, ler memory/projects.md
WriteCria arquivo novoGerar HTML, criar config, exportar relatorio
EditEdita arquivo existenteTrocar linha de codigo, atualizar memoria
WebFetchBaixa pagina webLer artigo, pegar dados publicos
WebSearchPesquisa no GoogleBuscar noticia recente, validar fato
AgentCria subagente em sessao isoladaDelegar 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).

CUIDADO COM BASH LIVRE
Bash livre = poder de executar qualquer comando no servidor. Em maos erradas (ou agente alucinando), pode rodar 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.

// CAP 11

Subagentes

Um agente sozinho fica sobrecarregado fazendo tudo. A solucao e dividir o trabalho. Cada subagente e um arquivo .md com personalidade propria. A Naia delega, eles executam, ela entrega o resultado.
Time de subagentes especialistas

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.
REGRA DA NAIA
Tarefa que demora mais de 30 segundos = delego pro subagente. A Naia mantem o foco em conversar com o Chefe e orquestrar. Quem executa e o time. E exatamente como uma CEO trabalha.
// CAP 12

Bot Telegram externo

Esse e o canal de comunicacao do Chefe com o agente. Daemon Python rodando como servico, sempre ligado, totalmente independente do Claude Code. Se o Claude cair, o bot continua recebendo mensagens.
Bot Python recebendo mensagens do Telegram

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

Bot Python
Daemon sempre ligado

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.

Pasta inbox/
Fila de entrada

Cada mensagem do Chefe vira 1 arquivo JSON. Audit log permanente. Se o Claude cair, mensagens ficam aqui esperando ele voltar.

tmux send-keys
Teclado fantasma

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.

Pasta outbox/
Fila de saida

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.
CONFIGURACAO COMO SERVICO
Pra o bot ser realmente "sempre ligado", configure ele como servico systemd no Linux ou launchd no Mac. Se cair, o sistema operacional restartar automaticamente. Voce esquece que ele existe e ele continua trabalhando.
// CAP 13

Pipeline ponta a ponta

Agora que voce conhece todas as pecas, vamos ver o caminho completo de uma mensagem. Do "oi" no Telegram ate a resposta de volta no Telegram, em segundos.
Pipeline ponta a ponta da mensagem

O caminho completo de uma mensagem

  1. Chefe digita no Telegram: "ve o status do servidor"
  2. Servidores do Telegram recebem e ficam segurando ate alguem buscar
  3. Bot Python faz polling a cada 1-2s e baixa a mensagem nova
  4. Bot grava arquivo inbox/12345.json com a mensagem
  5. Bot roda tmux send-keys -t naia "[telegram from Denderson msg_id=12345] ve o status do servidor" Enter
  6. Claude Code recebe como se voce tivesse digitado, prepara o pacote
  7. Naia chama POST 127.0.0.1:3007/search com 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.
  8. Claude Code empacota: system prompt (CLAUDE.md) + lista de tools + historico da conversa + chunks vetoriais + sua mensagem nova
  9. Claude Code faz POST https://api.anthropic.com/v1/messages
  10. Anthropic roteia pro Opus 4.7 num data center
  11. Opus 4.7 processa, decide chamar tool Bash com comando uptime; free -h; df -h /
  12. Anthropic devolve resposta com tool_use
  13. Claude Code executa o comando no servidor da VPS
  14. Claude Code manda o output de volta pro modelo numa segunda chamada
  15. Opus 4.7 gera resposta final em texto: "Servidor de pe ha 47 dias. RAM: 4.2GB de 15GB. Disco 38% usado."
  16. Claude Code imprime no terminal
  17. Naia grava arquivo outbox/12345.json com a resposta
  18. Bot Python detecta arquivo novo em outbox/
  19. Bot faz POST https://api.telegram.org/bot{TOKEN}/sendMessage
  20. Telegram entrega no celular do Chefe
  21. Bot move outbox/12345.json pra sent/12345.json e 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

FalhaOnde aconteceComo recuperar
Internet caiuVPS sem acesso a Anthropictmux mantem sessao viva, retoma quando volta
Anthropic foraAPI com 503Claude Code retry automatico
Bot Python travouDaemon parousystemd restarta em 5s
tmux session morreuComando errado matou o claudeBot detecta, recria sessao, reinicia
Token Telegram expirouBot nao consegue mais pollingRenovar com BotFather, atualizar .env
O QUE TORNA O SISTEMA RESILIENTE
Nada do pipeline depende de um unico ponto. Cada peca tem fila ou retry. Se o Claude cai, mensagens ficam em inbox/. Se o bot cai, systemd restarta. Se a internet cai, tmux espera. E por isso que o agente fica vivo 24/7.
// CAP 14

Como montar o seu

Voce ja entendeu cada peca. Agora e botar a mao na massa. Esse e o passo a passo do zero ao seu primeiro agente respondendo no Telegram.
Escada com 12 passos
passo zero
Hostinger // contrate sua VPS pra rodar o agente
hostinger.com.br/avalanche cupom AVALANCHE 10% off em VPS anual

Os 12 passos

  1. 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.

  2. Conecte via SSH

    No terminal do seu Mac/PC: ssh root@IP_DA_VPS. Atualize o sistema: apt update && apt upgrade -y.

  3. 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.

  4. Instale o Claude Code

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

    Vai criar o comando claude globalmente.

  5. 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_chunks com colunas id, 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 endpoints POST /search e POST /chunk. Crie um cron a cada 30min que le memory/ e knowledge/, 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.

  6. 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.

  7. 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.

  8. Crie 1 a 3 subagentes basicos

    Em .claude/agents/, crie pelo menos um dev.md e um copy.md. Use o template do cap 10.

  9. 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.

  10. Crie o bot no Telegram

    Abra @BotFather no Telegram. Mande /newbot, escolha um nome, copie o TOKEN. Anote o seu chat_id (use @userinfobot pra descobrir).

  11. 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.

  12. Configure systemd pra ficar 24/7

    Crie um arquivo /etc/systemd/system/agente-bot.service com restart automatico. Habilite com systemctl 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.

PROXIMOS PASSOS
1. Adicione mais subagentes conforme precisar (SDR, designer, analista)
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