Como ver quanto token sua sessão do Claude Code gastou com o /caveman-stats

Fala aí, beleza? Todo mundo tem uma opinião sobre quanto o modo caveman economiza de token, e quase ninguém tem o número da própria sessão

O /caveman-stats resolve isso do jeito chato e correto: ele lê o log da sessão atual do Claude Code, que está gravado em disco, e devolve os tokens reais de entrada e saída mais a economia estimada contra uma linha de base sem caveman

Ou seja, decidir se vale manter o modo ligado deixa de ser papo de timeline e vira leitura de relatório 🙂

O que você precisa antes de rodar o /caveman-stats:

Duas coisas: Claude Code instalado e o plugin caveman ativo

O caveman é um projeto de código aberto distribuído no repositório JuliusBrussee/caveman, e se apresenta como uma skill para o Claude Code que corta tokens fazendo o agente responder em estilo caveman

A skill de estatística mora dentro do próprio repositório, na pasta skills/caveman-stats, com README próprio em skills/caveman-stats/README.md

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

A instalação oficial é pelo marketplace de plugins, dois comandos, e os hooks são configurados automaticamente:

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

O INSTALL.md do repositório também oferece o caminho por script: baixar a URL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.2.0/install.sh, revisar o conteúdo e rodar com bash install.sh

No Windows sem WSL2, o mesmo INSTALL.md indica o install.ps1 via PowerShell

Tome cuidado com uma coisa aqui: o caveman-stats foi escrito para os caminhos e para o formato de log do Claude Code

Isso não é detalhe teórico, tem registro público: a issue #403 do repositório documenta o comando falhando no Gemini CLI justamente por causa desses caminhos e desse formato embutidos no código

Passo a passo para medir o gasto da sessão:

1. Instale o plugin com os dois comandos do marketplace que estão logo acima, e deixe os hooks entrarem sozinhos

O erro comum deste passo: sair caçando configuração manual de hook por conta própria, sendo que a instalação do plugin já cuida disso

2. Rode o comando dentro de uma sessão do Claude Code, na sessão que você quer medir:

/caveman-stats

O erro comum deste passo: esperar que isso funcione fora do Claude Code, em outro agente de terminal (ver a issue #403 ali de cima)

3. Entenda de onde vêm os números antes de acreditar neles

Os valores saem do arquivo JSONL da sessão gravado em disco, dentro do diretório de projetos do Claude Code (~/.claude/projects/)

Quem calcula não é o modelo, e o processamento é local, nada sai da máquina

A saída em si é injetada por um hook do plugin chamado caveman-mode-tracker, que intercepta o /caveman-stats e devolve as estatísticas formatadas como razão de decisão bloqueada

O erro comum deste passo: pedir pro modelo "calcular quanto eu gastei" em linguagem natural e tratar o chute dele como medição

4. Leia campo por campo do relatório

A saída traz contagem de turnos da sessão (session turn count), tokens de entrada (input tokens), tokens de saída em modo caveman (output tokens), o baseline estimado sem caveman (baseline tokens) e os tokens economizados (saved tokens)

E traz mais duas linhas que são as importantes: Est. rule overhead, o custo das regras injetadas, e Est. net, que é a economia já descontando esse custo

O erro comum deste passo: bater o olho no saved tokens, comemorar e ignorar o Est. net

5. Amplie a janela antes de concluir

Uma sessão só é uma amostra pequena e enviesada pelo que você fez naquele dia

/caveman-stats --all
/caveman-stats --since 7d
/caveman-stats --since 24h
/caveman-stats --share

O –all agrega todas as sessões, o –since recorta uma janela de tempo e o –share gera uma linha resumida compartilhável

O erro comum deste passo: comparar duas sessões de tamanhos completamente diferentes e achar que descobriu alguma coisa

Economia bruta, overhead e net: qual número olhar

Cada linha da saída responde uma pergunta diferente, e é fácil ler a linha certa com a pergunta errada na cabeça

O custo padrão de 1.250 tokens de input por turno pode ser sobrescrito pela variável de ambiente CAVEMAN_RULE_OVERHEAD_TOKENS, caso o seu setup injete um volume diferente do padrão

Se você mexe nisso em máquina de trabalho e quer que o time inteiro leia o mesmo número, vale pensar antes no que entra no repositório e no que fica local, igual acontece com a configuração do Claude Code em time

E tem um ponto de expectativa que precisa ser dito aqui, senão o relatório sempre vai parecer decepcionante

O README do projeto anuncia cerca de 65% a 75% de redução de tokens de saída

Já o snapshot de eval commitado no próprio repositório produz cerca de 50% de redução mediana contra o braço de controle terse, medido com a codificação tiktoken o200k_base usada pelo evals/measure.py

Além disso, a documentação do projeto delimita o escopo: o caveman não comprime o input, o contexto, os arquivos nem os tokens de raciocínio do modelo

Por isso o total da sua sessão pode divergir MUITO da variação medida só na saída, e isso não é bug do comando, é o que ele está medindo

Quando o número vem estranho: net negativo, selo e sessão vazia

Sintoma: o Est. net veio negativo

Causa: sessão de respostas curtas e terses, onde o custo das regras injetadas por turno come a economia de saída

O relatório diz isso na cara, em vez de mostrar só a economia bruta e fingir que está tudo lindo

O que fazer: aceitar o recado

O HONEST-NUMBERS.md do repositório registra os cenários em que o caveman custa mais do que economiza, citando perguntas e respostas curtas de código e sessões cobradas por requisição em vez de por token

Se o seu dia é feito de perguntinha rápida, o net negativo é a resposta, não o erro

Sintoma: apareceu um selo de economia na statusline e você não pediu

Causa: cada execução do comando grava um arquivo de economia acumulada, e esse valor vira o selo da statusline, atualizado a cada /caveman-stats

O que fazer: se incomoda, silencia com a variável de ambiente CAVEMAN_STATUSLINE_SAVINGS=0

Sintoma: o comando não devolve estatística nenhuma fora do Claude Code

Causa: os caminhos e o formato de log são do Claude Code, embutidos no código, e é exatamente isso que a issue #403 registra na falha com o Gemini CLI

O que fazer: rodar onde o comando foi feito pra rodar

Pra prevenir os três casos, a receita é a mesma: rode com –since numa janela que represente uma semana real de trabalho antes de tirar qualquer conclusão

Como usar esse número para decidir se mantém o modo ligado

Sessão longa, com muita saída gerada. É o cenário em que a economia bruta tem mais espaço pra superar o overhead por turno, então olhe o Est. net e veja se ele confirma

Sessão de perguntas curtas de código. Aqui o Est. net negativo é o resultado esperado, e a decisão honesta pode ser simplesmente não usar o modo nesse tipo de trabalho

Comparação semana a semana. Rode /caveman-stats –since 7d e compare com a leitura anterior, em vez de olhar a sessão de ontem e generalizar

Fechamento geral. O –all agrega todas as sessões e é o número que eu usaria pra bater o martelo, porque ele dilui o dia atípico

Esse hábito de medir antes de mudar o setup vale pra outras decisões do fluxo, tipo versionar o vault no Git antes de soltar o agente nas suas notas

E se você quiser ir além da leitura da sessão, o repositório tem uma pasta evals/ que mede a compressão real rodando os mesmos prompts no Claude Code em três condições e comparando a contagem de tokens de saída, com o script evals/measure.py

Vale lembrar também que o stats não é a única skill distribuída ali: existem as pastas skills/caveman, skills/caveman-commit e skills/caveman-help no mesmo repositório

Conclusão

O /caveman-stats não existe pra você postar print de economia, ele existe pra você parar de chutar

A régua de decisão é o Est. net, não o saved tokens: economia bruta sem descontar os 1.250 tokens de input por turno das regras injetadas é meia informação

E lembre do escopo: input, contexto, arquivos e tokens de raciocínio não são comprimidos, então o total da sessão nunca vai espelhar a variação medida só na saída

Próximo passo? Use o Claude Code normalmente por uma semana, rode /caveman-stats –since 7d e compare com a leitura de hoje

Se o net segurar positivo no seu tipo de trabalho, ótimo, deixa ligado

Se não segurar, você tem o número pra desligar sem culpa 😀

até o próximo post!