Caveman learn e o Cave Score: como descobrir onde seus tokens estão vazando

Numa sessão típica de cerca de 100 mil tokens, as respostas em prosa somam por volta de 6 mil tokens

Ou seja: o texto que o modelo escreve pra você, aquele que todo mundo tenta encurtar, é a menor parte da conta

O grosso está do outro lado, na entrada: histórico da conversa, conteúdo de arquivo, system prompt, tudo isso reenviado a cada turno

E aí entra o caveman learn, um comando que não chuta nada: ele escaneia o histórico real do agente, pontua e ranqueia os sumidouros de token, e devolve um relatório com o Cave Score na frente

Se você já tentou auditar o gasto de uma tarefa na mão, sabe o tamanho da chatice

A proposta aqui é essa mesma auditoria, só que automática e em cima do que VOCÊ já rodou

De skill de fala a motor de compressão: de onde vem o caveman

O caveman é um projeto open source de Julius Brussee, mantido no repositório JuliusBrussee/caveman

Ele nasceu como uma coisa quase de meme: uma skill que fazia o agente responder em estilo caveman (fala truncada, sem artigo, sem enrolação) pra cortar tokens de saída

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

A v2 mudou o alvo

Em vez de encurtar o que o modelo escreve, ela passou a comprimir o que o modelo LÊ: saídas de ferramenta, logs, código e JSON são comprimidos antes de entrarem no modelo

Faz sentido, né? Se o volume mora na entrada, é lá que o corte pesa

Os marcos recentes: a v2.1.0 saiu em 16 de agosto de 2026 e trouxe o context-depth report mais a vitrine do comando de diagnóstico no README

A v2.2.0 é a versão fixada no instalador

Tração o projeto tem de sobra: 98.774 estrelas no GitHub e 438.679 instalações em 18/08/2026

E tem outro detalhe que explica o pacote de hoje: caveman-code, cavekit e cavemem estão marcados como Frozen, com o desenvolvimento ativo movido pro repositório caveman

O núcleo de memória comprimida do cavemem passou a ser embarcado no caveman, o que importa mais adiante quando a gente falar de offload

Como instalar o caveman e rodar o primeiro diagnóstico

A instalação unificada é um one-liner de curl que roda o install.sh do repositório

1. Inspecione antes de aplicar, com o dry-run:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.2.0/install.sh | bash -s -- --dry-run

O erro comum deste passo é o clássico: jogar um script da internet direto no bash sem olhar o que ele faz

O --dry-run existe pra isso, use ele

Com a inspeção feita, você repete a mesma linha sem a flag

2. Se você quer instalar só pra um agente, use --only <id> (por exemplo claude, gemini ou codex)

O instalador é idempotente e pode ser reexecutado, então rodar de novo não quebra nada

O erro comum aqui é achar que reexecutar duplica config e sair caçando arquivo pra apagar na mão

3. Dentro do Claude Code, tem o caminho de plugin pelo marketplace do próprio repositório:

/plugin marketplace add JuliusBrussee/caveman
/plugin install caveman@caveman

O erro comum: misturar os dois caminhos sem necessidade

Escolha um e siga

4. Rode o diagnóstico:

caveman learn

O instalador detecta automaticamente os agentes presentes na máquina e roda o caminho de instalação nativo de cada um, com auto-detecção de mais de 30 agentes, entre eles Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Copilot, Continue, Goose e Aider

O erro comum deste último passo é mental: gente que trava achando que precisa criar conta ou que o histórico vai ser enviado pra algum servidor

Não vai

O comando roda localmente, com acesso somente leitura ao histórico e sem exigir conta

O relatório vem com cinco blocos: o Cave Score, cada sumidouro ranqueado por fluxo com um fix de uma linha atrás de cada linha, quão fundo cada sessão entrou na janela de contexto, um replay do que os fixes teriam cortado nas sessões passadas e uma ilustração de custo a preço de tabela em 30 dias

Um aviso honesto: a escala do Cave Score e a fórmula da nota não estão documentadas nas fontes públicas

Então trate a primeira execução como SUA linha de base, não como uma nota universal pra comparar com o vizinho

As quatro classes de sumidouro: como interpretar cada linha do relatório

Aqui é onde a pontuação vira leitura acionável

Cada sumidouro do relatório vem etiquetado com uma classe, e a classe define o que fazer com ele

Se liga nessas duas últimas, que é onde a ferramenta ganha respeito

O habit vem com números MAIS uma sugestão suave, nunca uma ordem

E o load-bearing é contado no score e nunca é tocado, ou seja, a ferramenta não te empurra pra destruir a config que faz seu setup funcionar só pra melhorar a nota

Isso muda a leitura: um Cave Score que não é perfeito pode estar certíssimo

Do diagnóstico à mudança de hábito: implement e applied

Relatório bonito que ninguém aplica não economiza um token sequer, beleza?

Então tem o caminho de execução

1. Entregue o plano ao seu próprio agente:

caveman learn implement

Esse comando usa a skill caveman-learn, que manda propor cada fix como diff, aplicar só com o seu sim, re-medir e reverter o que não baixou os tokens por turno

Repare no detalhe mais importante: a reversão automática do que não reduziu tokens por turno

É o oposto do "aplica tudo e reza"

O erro comum deste passo é sair dando sim em tudo sem ler o diff

O consentimento é por edição justamente pra você olhar

2. Já arrumou uma coisa na mão? Registre:

caveman learn applied <sink_id>

As execuções seguintes indicam se o resultado melhorou, ficou igual, regrediu ou precisa de mais dados

Esse "precisa de mais dados" é uma resposta honesta e rara de se ver em ferramenta de otimização

O erro comum aqui é esperar veredito na execução seguinte, com duas sessões de amostra

3. Use o context-depth report como termômetro entre uma rodada e outra

Ele mostra o pico de share da janela de contexto por sessão, agrupado em faixas, com contagem de sessões acima de 30% e acima de 50%

É um número que conversa direto com o tamanho da janela que você tem à disposição, e a régua muda MUITO de modelo pra modelo, como no caso do contexto de 1M de tokens do Gemini

Se suas sessões vivem acima de 50%, o problema não é a prosa da resposta

E tem a skill caveman-stats pra medir sem achismo: os números vêm do log JSONL da sessão em disco, o modelo não calcula nem estima

A saída é injetada pelo hook caveman-mode-tracker, que intercepta /caveman-stats

Quanto isso economiza de verdade

Agora a parte que interessa, e vou dar os dois lados

O número autodeclarado do projeto pro modo com proxy vem de um benchmark fixado: 54 execuções no Claude Code, 33,2% menos tokens de entrada reportados pelo provedor que o Claude Code direto, passando os 18 checks de resposta exata

Do outro lado, testes independentes bateram de frente com os 65% a 75% divulgados pra skill de fala caveman

Em teste pareado, a economia converge pra cerca de 8,5% em escala: de 592 mil pra 542 mil tokens de saída em 82 tarefas pareadas

8,5% contra 65%? Parece contradição, mas não é

São coisas DIFERENTES sendo medidas

A skill de fala corta prosa de saída, e a prosa é aquela fatia pequena que a gente citou lá em cima

Cortar boa parte de uma fatia pequena continua sendo pouco no total

Já o modo com proxy mexe na entrada, que é onde o volume mora, e por isso o número muda de patamar

E tem o custo do outro lado da conta, que quase ninguém lembra: as regras injetadas em toda requisição têm um overhead estimado, com padrão de 1.250 tokens por turno, sobrescrevível pela variável CAVEMAN_RULE_OVERHEAD_TOKENS

Em sessão curta, esse pedágio por turno pesa proporcionalmente mais

O que muda para quem usa Claude Code no dia a dia

O valor do caveman learn não é a porcentagem prometida, é a medição do SEU histórico

Ninguém consegue te dizer quanto você vai economizar sem olhar o que você faz, e é exatamente isso que o comando faz

Dois padrões que aparecem como custo fixo em TODO turno:

• CLAUDE.md inchado: cada linha que você escreveu lá viaja em toda requisição, pra sempre
• Skill que você nunca invoca: ocupa espaço no orçamento e não entrega nada

Esses são safe fix, o ganho fácil

Já aquele bloco de contexto que você recola toda santa sessão é candidato a offload, movido pra memória do caveman quando o recall medir mais barato que recolar

E olha, quem só quer o diagnóstico não é obrigado a comprar o pacote inteiro

Dá pra rodar o comando, ler o relatório, aplicar os fixes na mão e ignorar o resto

O que NÃO dá pra afirmar sem medir na sua máquina: quanto sobra no seu bolso

Os dois números que existem (os 33,2% do benchmark do projeto e os 8,5% do teste pareado independente) foram medidos em cenários específicos, com tarefas específicas

O seu fluxo é outro

Conclusão

O recado é simples: pare de tentar adivinhar onde o token vaza

Rode caveman learn uma vez, leia o Cave Score como linha de base, e comece só pelos safe fix (o CLAUDE.md inchado e a skill que você nunca chama)

Depois re-mede e compara, seja pelo caveman learn implement com diff e reversão automática, seja registrando na mão com caveman learn applied <sink_id>

Na sua próxima sessão, faça o teste: rode o comando ANTES de abrir a tarefa, olhe o context-depth report e veja quantas sessões suas passaram de 50% da janela

Se passaram várias, você acabou de achar seu vazamento 🙂

até o próximo post!