Como rastrear os custos do Claude Code por mensagem (sem ferramentas de terceiros)

O Claude Code é um dos agentes de programação com IA mais poderosos disponíveis hoje. Ele consegue refatorar bases de código inteiras, escrever suítes de testes do zero e depurar problemas complexos que envolvem múltiplos arquivos em minutos. Mas todo esse poder vem com um custo surpreendentemente difícil de monitorar. Desenvolvedores relatam rotineiramente gastar US$ 50, US$ 100 ou até mais de US$ 300 por dia com o Claude Code sem perceber, até a fatura chegar.

O problema central é a visibilidade. O Claude Code roda no seu terminal, processa milhares de tokens por interação e não te dá nenhum feedback em tempo real sobre quanto custa cada mensagem. Você termina uma sessão de programação, confere o seu painel da Anthropic no dia seguinte e descobre que torrou todo o seu orçamento mensal numa tarde.

Este guia aborda por que rastrear os custos do Claude Code importa, quais ferramentas existem atualmente e como obter visibilidade de custo por mensagem em tempo real usando o SuperBuilder — um app de desktop gratuito e open source para agentes de programação com IA.

Por que os custos do Claude Code saem do controle

O Claude Code não é um chatbot simples. Quando você pede para ele "refatorar o módulo de autenticação", ele lê dezenas de arquivos, constrói um modelo mental da sua base de código, escreve código, roda testes, lê a saída de erro e itera. Um único prompt pode disparar uma cadeia de chamadas de ferramentas que consome dezenas de milhares de tokens ao longo de vários turnos.

Veja o que torna os custos imprevisíveis:

Janelas de contexto grandes são caras

O Claude Code usa o Claude 3.5 Sonnet ou o Claude 3 Opus por baixo dos panos. Cada interação inclui o seu prompt de sistema, o histórico da conversa, o conteúdo dos arquivos e os resultados das ferramentas. Uma mensagem típica no meio de uma sessão pode carregar de 50.000 a 100.000 tokens de entrada antes mesmo de o Claude começar a gerar uma resposta. Com a precificação atual da Anthropic, só esse contexto custa de US$ 0,15 a US$ 0,30 por mensagem no Sonnet, e significativamente mais no Opus.

O uso de ferramentas multiplica o consumo de tokens

Quando o Claude Code lê um arquivo, ele passa a fazer parte do contexto da conversa. Quando ele roda um comando e lê a saída, são mais tokens. Um único prompt do tipo "corrija este bug" pode resultar em 5 a 15 chamadas de ferramentas, cada uma adicionando milhares de tokens ao contexto acumulado. A conversa cresce a cada turno, e você paga pelo contexto completo em cada mensagem subsequente.

Nenhum feedback de custo integrado

A CLI do Claude Code te mostra a resposta. Ela não te mostra a contagem de tokens, o custo ou sequer um aviso quando você está se aproximando de um limite de gastos. Você está voando às cegas. Esse é o problema fundamental — desenvolvedores não conseguem otimizar o que não conseguem ver.

A duração da sessão agrava o problema

Quanto mais longa a sua sessão, maior a janela de contexto e mais cara fica cada mensagem. Uma sessão recém-iniciada pode custar US$ 0,02 por mensagem. Depois de 30 turnos de depuração de idas e vindas, o mesmo tipo de mensagem pode custar US$ 0,50 ou mais, porque o histórico inteiro da conversa é incluído em cada requisição.

Soluções existentes para rastrear os custos do Claude Code

Antes de chegarmos ao rastreamento em tempo real, vamos analisar o que está disponível hoje e onde cada abordagem deixa a desejar.

Painel do Anthropic Console

O Anthropic Console em console.anthropic.com fornece métricas de uso da sua conta de API. Você consegue ver o total de tokens consumidos e o gasto total, segmentado por dia e por modelo.

O que ele faz bem:

• Fonte oficial de verdade para cobrança
• Mostra agregados diários e mensais
• Segmenta o uso por modelo (Sonnet vs. Opus)

O que falta:

• Sem granularidade por mensagem — você vê totais diários, não interações individuais
• Sem associação a projetos ou sessões de programação específicas
• Os dados têm atraso — você está sempre olhando para o uso passado, não para o gasto atual
• Sem alertas ou limites — você descobre os excessos só depois que acontecem

O painel da Anthropic é útil para a contabilidade mensal, mas não te diz nada sobre qual sessão ou prompt específico foi caro. Se você gastou US$ 40 ontem, não tem como saber se foi a refatoração da autenticação ou a geração da suíte de testes que devorou seu orçamento.

ccusage (ferramenta de CLI open source)

O ccusage é uma ferramenta de CLI construída pela comunidade que analisa os arquivos de log locais do Claude Code para calcular o uso de tokens e os custos estimados. Você a executa depois de uma sessão, e ela exibe um detalhamento das suas interações recentes.

O que ele faz bem:

• Gratuito e open source
• Fornece detalhamentos de custo por sessão
• Funciona localmente, sem enviar dados para lugar nenhum
• Consegue analisar sessões históricas

O que falta:

• Apenas em retrospecto — você o roda depois que o estrago já foi feito
• Requer invocação manual — você precisa se lembrar de verificar
• Saída apenas em CLI — sem painel visual ou gráficos
• Sem feedback em tempo real durante sessões de programação ativas
• As estimativas podem divergir da cobrança real por causa de caching e otimizações de prompt

O ccusage é uma ferramenta sólida para revisar sessões passadas. Mas ele não resolve o problema central: você precisa de visibilidade de custo enquanto programa, não depois de já ter gasto o dinheiro.

Contagem manual de tokens

Alguns desenvolvedores rastreiam custos estimando contagens de tokens manualmente. Eles têm uma ideia aproximada de quão grandes são os arquivos da sua base de código, estimam o tamanho da janela de contexto e multiplicam pelos preços de token publicados.

Isso é tedioso, propenso a erros e desmorona completamente quando o Claude Code encadeia múltiplas chamadas de ferramentas. Ninguém vai pausar no meio de uma sessão para calcular que a última mensagem incluiu 47.000 tokens de entrada de três leituras de arquivo e duas saídas de comando.

Como é o rastreamento de custo por mensagem em tempo real

A peça que falta é uma ferramenta que te mostre o custo de cada mensagem conforme ela acontece — não depois da sessão, não como um agregado diário, mas ali mesmo na interface, ao lado de cada resposta.

É isso que o SuperBuilder oferece. O SuperBuilder é um app de desktop gratuito e open source que envolve o Claude Code em uma interface nativa e adiciona recursos que faltam na CLI, incluindo rastreamento de custo por mensagem em tempo real.

Como funciona

O SuperBuilder inicia o Claude Code como um processo filho usando a flag --output-format stream-json. Isso dá ao SuperBuilder acesso ao fluxo estruturado de eventos que o Claude Code emite, incluindo os dados de uso de tokens de cada interação.

Para cada troca de mensagens, o SuperBuilder extrai:

• Tokens de entrada: O contexto total enviado ao modelo (prompt de sistema + histórico da conversa + conteúdo dos arquivos + resultados das ferramentas)
• Tokens de saída: Os tokens que o Claude gerou na sua resposta
• Tokens de leitura de cache: Tokens servidos pelo caching de prompt da Anthropic (mais baratos que tokens de entrada novos)
• Tokens de escrita de cache: Tokens gravados no cache para reuso futuro
• Custo total em USD: Calculado a partir das contagens de tokens usando a precificação atual da Anthropic

Esses dados são exibidos junto a cada mensagem, armazenados em um banco de dados SQLite local e disponibilizados em um resumo de custo da sessão.

O que você vê por mensagem

Toda resposta do Claude no SuperBuilder mostra um pequeno selo de custo. Clique ou passe o mouse sobre ele, e você verá o detalhamento completo:

Message #12
Input tokens:   72,431
Output tokens:   1,847
Cache read:     58,200
Cache write:    14,231
Cost:           $0.18

Isso te diz instantaneamente que a mensagem nº 12 foi cara porque a janela de contexto estava grande (72 mil tokens de entrada), mas o caching ajudou a reduzir o custo (58 mil tokens servidos do cache a uma taxa menor).

Ao longo de uma sessão, você desenvolve uma intuição sobre quais tipos de prompts são caros e quais são baratos. Você começa a notar padrões: "Toda vez que peço para ele ler aquele arquivo de configuração grande, o custo dispara" ou "Mensagens em modo de planejamento são consistentemente mais baratas que edições diretas".

Resumo de custo da sessão

No nível da thread, o SuperBuilder rastreia o custo cumulativo da sessão inteira. Você consegue ver, num relance:

• Gasto total desta thread
• Número de mensagens trocadas
• Custo médio por mensagem
• Mensagem individual mais cara
• Tendências de uso de tokens ao longo da sessão

Isso te dá o ciclo de feedback que está completamente ausente na experiência padrão da CLI do Claude Code.

Configurando o rastreamento de custos no SuperBuilder

Começar leva cerca de dois minutos.

Passo 1: Baixe o SuperBuilder

O SuperBuilder está disponível para macOS (Apple Silicon e Intel). Baixe-o em superbuilder.sh/download.

Passo 2: Conecte sua chave de API da Anthropic

No primeiro início, o SuperBuilder pede sua chave de API da Anthropic. É a mesma chave que você usa com o Claude Code no terminal. O SuperBuilder não armazena sua chave em nenhum servidor — ela fica na sua máquina e é passada diretamente para o processo do Claude Code.

Passo 3: Inicie uma thread

Crie uma nova thread, selecione o diretório do seu projeto e comece a programar. O rastreamento de custos é automático — não há nada para configurar. Toda mensagem mostrará seu custo assim que o Claude responder.

Passo 4: Revise seus gastos

A qualquer momento, você pode revisar o detalhamento de custos da sua sessão atual. O selo de custo em cada mensagem te dá visibilidade instantânea por interação, e o resumo da thread mostra o gasto cumulativo.

Dicas práticas para reduzir os custos do Claude Code

Agora que você consegue ver quanto custa cada mensagem, aqui estão estratégias concretas para manter seus gastos sob controle.

1. Mantenha as janelas de contexto pequenas

O maior fator de custo isolado é a contagem de tokens de entrada. Cada arquivo que o Claude leu, cada saída de comando, cada mensagem anterior — tudo se acumula na janela de contexto e você paga por isso a cada turno.

O que fazer:

• Inicie novas sessões com frequência, em vez de manter conversas de 50 turnos
• Seja específico sobre quais arquivos olhar ("leia src/auth/login.ts" em vez de "olhe o módulo de autenticação")
• Evite pedir ao Claude para ler arquivos grandes que não são relevantes para a tarefa atual

2. Use o modo de planejamento para tarefas complexas

O SuperBuilder oferece modos de execução incluindo o modo de planejamento (Plan Mode), que instrui o Claude a esboçar sua abordagem antes de escrever código. Isso é mais barato porque:

• A resposta de planejamento é em grande parte texto (poucos tokens de saída em relação à geração de código)
• Você pode corrigir o rumo antes de o Claude gastar tokens na abordagem errada
• Isso evita ciclos caros de "desfazer e refazer"

Uma mensagem de planejamento normalmente custa de 30% a 50% menos que uma mensagem de geração direta de código, e reduz a chance de mensagens de acompanhamento desperdiçadas.

3. Agrupe alterações relacionadas

Em vez de enviar cinco prompts separados ("adicione tratamento de erro à função A", "adicione tratamento de erro à função B" etc.), agrupe-os em um único prompt: "Adicione tratamento de erro às funções A, B, C, D e E em src/api/handlers.ts."

Um prompt bem estruturado com uma resposta detalhada é quase sempre mais barato que cinco idas e vindas, porque cada ida e volta inclui o contexto completo da conversa.

4. Use o modelo certo para a tarefa

Nem toda tarefa precisa do modelo mais poderoso. Formatação simples de código, adição de comentários ou escrita de boilerplate podem ser feitas pelo Sonnet por uma fração do custo do Opus. Reserve o Opus para decisões arquiteturais complexas, depurações difíceis e tarefas que exijam raciocínio profundo.

5. Monitore a taxa de acerto do cache

O SuperBuilder mostra os tokens de leitura de cache separadamente. Uma alta proporção de leitura de cache significa que você está tendo um bom custo-benefício — tokens em cache custam significativamente menos que tokens de entrada novos. Para maximizar os acertos de cache:

• Mantenha suas sessões focadas em um conjunto consistente de arquivos
• Evite alternar abruptamente entre partes não relacionadas da base de código na mesma sessão
• Reutilize sessões ao continuar o trabalho na mesma funcionalidade

6. Defina um orçamento mental por sessão

Com o rastreamento de custo por mensagem, você pode definir um limite pessoal. Por exemplo: "Vou iniciar uma nova sessão se esta passar de US$ 2." Essa regra simples evita sessões descontroladas em que a janela de contexto incha e cada mensagem fica desproporcionalmente cara.

7. Fique atento a loops caros de chamadas de ferramentas

Às vezes o Claude fica preso em um loop — rodando um comando, lendo o erro, tentando uma correção, rodando o comando de novo. Cada iteração se soma ao contexto e custa dinheiro. Se você notar o custo por mensagem subindo abruptamente, interrompa a sessão e forneça orientação mais clara ou comece do zero.

Comparação: ferramentas de rastreamento de custos do Claude Code

Aqui está uma comparação direta das três principais abordagens para rastrear os custos do Claude Code.

O grande diferencial é o momento. O Anthropic Console e o ccusage te dizem o que você gastou. O SuperBuilder te diz o que você está gastando agora, mensagem por mensagem, para que você possa ajustar seu comportamento em tempo real.

Alertas de chamadas grandes

O SuperBuilder inclui um alerta configurável para mensagens caras. Por padrão, qualquer mensagem individual que custe mais de US$ 0,10 dispara um cartão de aviso no chat. Isso é útil para identificar interações inesperadamente caras antes que elas se transformem em uma sessão custosa.

Você pode ajustar o limite nas Configurações de acordo com seu orçamento e seus padrões de uso.

Padrões de custo do mundo real

Depois de rastrear custos em milhares de interações com o Claude Code, alguns padrões emergem:

Custos típicos de mensagem (Claude 3.5 Sonnet)

• Pergunta simples sobre código: US$ 0,01–US$ 0,03
• Ler um arquivo e explicá-lo: US$ 0,03–US$ 0,08
• Escrever uma nova função: US$ 0,05–US$ 0,15
• Refatorar um arquivo existente: US$ 0,08–US$ 0,25
• Depurar com múltiplas chamadas de ferramentas: US$ 0,10–US$ 0,50
• Alterações grandes em múltiplos arquivos: US$ 0,20–US$ 1,00+

Faixas de custo por sessão

• Correção rápida de 5 mensagens: US$ 0,10–US$ 0,50
• Funcionalidade moderada de 20 mensagens: US$ 1,00–US$ 5,00
• Sessão estendida de mais de 50 mensagens: US$ 5,00–US$ 25,00+

Essas faixas variam significativamente com base no tamanho da base de código, no comprimento dos arquivos e em quantas chamadas de ferramentas o Claude faz. O ponto não são os números exatos — é que, sem rastreamento por mensagem, você não tem ideia de onde se encaixa nessas faixas até o fim da sessão.

Perguntas frequentes

O SuperBuilder adiciona algum custo além do Claude Code?

Não. O SuperBuilder é gratuito e open source. Você paga apenas pelos tokens da API da Anthropic consumidos pelo Claude Code, exatamente como faria usando a CLI diretamente. O SuperBuilder não adiciona nenhum token, não faz proxy das suas requisições e não cobra nenhuma taxa.

Quão preciso é o rastreamento de custos?

O SuperBuilder lê as contagens de tokens diretamente do fluxo de saída JSON estruturado do Claude Code. As contagens de tokens são exatas. O custo em USD é calculado usando a precificação publicada pela Anthropic, que pode mudar com o tempo. O SuperBuilder atualiza a precificação conforme a Anthropic publica mudanças.

Posso exportar meus dados de custo?

Todos os dados de custo são armazenados em um banco de dados SQLite local na sua máquina. Você pode consultá-lo diretamente ou usar a interface do SuperBuilder para revisar custos por thread e por mensagem. A funcionalidade de exportação para CSV e JSON está no roadmap.

Isso funciona com assinaturas Claude Max ou Claude Pro?

O rastreamento de custos do Claude Code no SuperBuilder se aplica ao uso da API. Se você estiver usando o Claude Code por meio de uma assinatura Max ou Pro em vez de cobrança por API, as contagens de tokens por mensagem ainda são rastreadas e exibidas, embora o cálculo do custo em USD possa diferir da precificação da sua assinatura.

Meus dados são enviados para algum lugar?

Não. O SuperBuilder roda inteiramente na sua máquina. Sua chave de API, dados de conversa e métricas de custo nunca saem do seu computador. Não há telemetria, nem analytics, nem sincronização na nuvem.

Como começar

Se você usa o Claude Code e quer visibilidade sobre quanto custa cada mensagem, o SuperBuilder te dá isso em um app de desktop gratuito e open source.

1. Baixe o SuperBuilder em superbuilder.sh/download
2. Adicione sua chave de API da Anthropic
3. Comece a programar — o rastreamento de custos é automático

Toda mensagem mostrará seu uso de tokens e seu custo em USD. Você começará imediatamente a tomar decisões mais inteligentes sobre como estruturar prompts, quando iniciar novas sessões e quais tarefas justificam o gasto.

Pare de adivinhar quanto custa o Claude Code. Comece a rastrear por mensagem, em tempo real.

Baixe o SuperBuilder gratuitamente