Comparativo de rastreadores de gastos do Claude Code

O que um rastreador de custos do Claude Code lê na realidade

Todos os rastreadores de custos do Claude Code leem uma de três fontes de dados, e a fonte determina a pergunta à qual conseguem responder. Um analisador de logs lê os ficheiros de transcrição das sessões no seu próprio disco. Um dashboard lê os registos de utilização que a Anthropic mantém para a sua conta ou organização. Um backend de métricas lê o fluxo OpenTelemetry (OTel) que o Claude Code emite quando o ativa. As três fontes podem estar corretas ao mesmo tempo e, ainda assim, apresentar valores diferentes, porque contam coisas diferentes.

Este guia não volta a explicar os tokens. como o Claude Code contabiliza a utilização de tokens descreve os tokens de entrada, de saída, as gravações na cache e as leituras da cache, e nenhum dashboard é muito útil enquanto essa parte não estiver clara. A questão aqui é mais específica: para cada tipo de ferramenta, o que consegue ver e o que nunca consegue ver.

Por que surgiram três rastreadores de gastos do Claude Code no mesmo dia

Três rastreadores de gastos diferentes do Claude Code foram publicados no mesmo dia. Não eram três versões da mesma ferramenta, e essa é a parte útil. Um analisava os ficheiros de sessão locais. Outro envolvia as telas de utilização da conta. O terceiro era um backend de rastreamento alojado que você executa por conta própria.

Eles surgiram juntos porque o custo de uma sessão de agente deixou de ser óbvio. Uma conversa custa aproximadamente o que é possível ver na tela. Um agente lê vinte ficheiros, executa a suíte de testes e reenvia toda a conversa a cada turno. Por isso, a cobrança é determinada pelo contexto que você nunca digitou. Numa assinatura, não há sequer um valor em dólares. Há apenas uma barra de utilização que se esvazia mais rapidamente em alguns dias do que em outros. Cada uma das três ferramentas preenche uma parte diferente dessa lacuna.

Forma 1: um parser local de logs mostra o custo de hoje

O Claude Code armazena cada conversa como JSON Lines (JSONL) em ~/.claude/projects/<project>/<session-id>.jsonl, onde <project> é o caminho do diretório de trabalho, com os caracteres não alfanuméricos substituídos por -. Cada interação do assistente nesse ficheiro contém as contagens de tokens do pedido. Um parser de logs soma essas contagens e calcula o preço.

ccusage é a opção escolhida pela maioria das pessoas. Não requer instalação:

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily calcula os totais por data. --breakdown divide cada linha por modelo, que é como se descobre que uma tarde com Opus representa a maior parte da semana. blocks agrupa os dados pela janela de cinco horas em que uma subscrição é reposta. session calcula os totais por conversa, e --instances agrupa-os por projeto para mostrar qual repositório é mais caro. Adicione --since e --until para limitar o intervalo e execute npx ccusage@latest daily --help para verificar o formato de data esperado pela sua versão. Em agosto de 2026, a ferramenta também lê outros CLIs de agentes, incluindo Codex e OpenCode, o que é útil para os comparar.

Os preços vêm de uma tabela de preços dos modelos, e a ferramenta tem três modos de custo. --mode auto usa o valor costUSD escrito pelo Claude Code no ficheiro, quando está presente, e calcula o custo a partir das contagens de tokens quando não está. --mode calculate calcula sempre o custo a partir dos tokens e ignora qualquer custo registado. --mode display mostra apenas os custos registados e imprime $0.00 nas linhas que não têm nenhum. Se um total parecer incorreto, execute o mesmo relatório com calculate e depois com display. Uma diferença grande entre os dois significa que a maioria das entradas não tem custo registado, pelo que todos os valores apresentados são estimativas.

Os mesmos dados podem alimentar o seu prompt. ccusage statusline imprime uma linha compacta para a barra de estado do Claude Code, integrada em ~/.claude/settings.json como qualquer outro comando de linha de estado. Consulte criar uma statusline do Claude Code para ver o bloco de definições e os campos que recebe.

Um parser de logs não consegue ver nada que não tenha acontecido nesta máquina. Um segundo portátil, uma sessão em claude.ai ou o trabalho de um colega: essas transcrições estão armazenadas nesses discos. Também faltam dados antigos, porque as transcrições são limpas ao fim de 30 dias por predefinição através da definição cleanupPeriodDays. Por isso, os dados do último trimestre desaparecem se não tiver feito um arquivo.

Existe ainda outro risco, de natureza estrutural. A documentação da Anthropic afirma que o formato das entradas é interno do Claude Code e muda entre versões. Por isso, os scripts que analisam diretamente estes ficheiros podem deixar de funcionar em qualquer release. Isto aplica-se a todas as ferramentas deste tipo. É também a razão pela qual um one-liner jq feito manualmente sobre o JSONL é uma opção pior do que parece: os parsers mantidos acompanham as alterações de formato, enquanto o seu one-liner apresentará um número incorreto com toda a aparência de confiança no dia em que um campo mudar de nome.

Por fim, o valor em dólares requer uma ressalva quando existe uma subscrição. Não é faturado por token nos planos Pro ou Max. Por isso, o número corresponde ao custo que os seus tokens teriam ao preço publicado da API. Mede a intensidade da sua utilização. Não corresponde à sua fatura. Se a questão real for qual é o plano mais adequado, essa comparação é uma análise à parte: consulte faturação da API comparada com uma subscrição Claude.

Forma 2: os ecrãs de utilização integrados mostram qual modelo consumiu o orçamento

O Claude Code inclui os seus próprios relatórios, mas a maioria das pessoas nunca os abre. Execute /usage dentro de uma sessão. O bloco Session, no topo, mostra os tokens por modelo e um valor em dólares para a sessão atual, calculado localmente a partir das contagens de tokens e das tarifas de tabela padrão. Esse valor não considera descontos nem preços promocionais, pelo que pode ser diferente do valor da fatura. Os totais são repostos quando /clear inicia uma nova conversa.

Num plano Pro, Max, Team ou Enterprise, o mesmo ecrã mostra quanto do limite do plano foi utilizado e atribui a utilização recente a skills, subagentes, plugins e servidores MCP individuais, como percentagem do total. Também assinala comportamentos que representam 10% ou mais da utilização recente, como contexto longo ou falhas de cache. Prima d ou w para alternar entre as últimas 24 horas e os últimos 7 dias. Estes valores são aproximados e calculados a partir do histórico de sessões local neste computador, pelo que um segundo dispositivo não é contabilizado. Quando essa barra está vazia, em vez de apenas baixa, o ecrã informa que a janela foi encerrada, mas não explica como continuar a trabalhar. O que fazer depois de atingir o limite é uma decisão separada sobre o modelo, o contexto e o plano.

Quando há mais do que um developer, os números passam para a conta. Uma organização API tem acesso à página de utilização da Console, a um dashboard do Claude Code com o gasto e as linhas aceites por membro, e a uma API de Analytics do Claude Code que devolve as mesmas métricas diárias por utilizador mediante uma chave de administrador. Os planos Teams e Enterprise têm um relatório de gastos na consola de administração, com exportação CSV e atualização diária. O Enterprise acrescenta uma API de analytics. Os dados que vê dependem da forma como cada developer iniciou sessão, pelo que uma organização mista tem de consultar dois relatórios e somar os valores manualmente.

Para dimensionar um orçamento, o valor publicado na documentação de custos da Anthropic, em agosto de 2026, é uma média próxima de $13 por developer por dia ativo e de $150 a $250 por developer por mês, com 90% dos utilizadores abaixo de $30 por dia ativo. Trate esse valor como uma referência publicada a partir de implementações empresariais, não como uma previsão para a sua equipa. Execute um piloto com um grupo restrito e meça os resultados antes de extrapolar.

Os dashboards não conseguem ver nada abaixo da granularidade do dia e da pessoa. Informam que o Opus foi responsável pela maior parte da utilização de terça-feira. Não informam qual prompt, repositório ou tarefa de CI a causou. Também têm atraso, porque os relatórios da organização são atualizados diariamente. Por isso, servem para revisão e não para detetar um agente descontrolado esta tarde. Para detetar e conter esse comportamento são necessários limites, não relatórios. Esse é o tema de manter os custos do agente dentro de limites num VPS.

Formato 3: a sua própria stack OpenTelemetry mostra qual prompt regrediu

O Claude Code emite métricas e eventos OpenTelemetry depois de definir uma variável de ambiente, e esta é a única opção que transmite dados de tokens e custos por utilizador para um sistema sob o seu controlo, quase em tempo real. As métricas incluem claude_code.cost.usage em USD, claude_code.token.usage em tokens, claude_code.session.count e claude_code.active_time.total.

A métrica de tokens é a mais interessante por causa dos seus atributos. Cada ponto de dados inclui type, que pode ser input, output, cacheRead ou cacheCreation, além de model e query_source, que pode ser main, subagent ou auxiliary. Também inclui agent.name, skill.name, mcp_server.name e mcp_tool.name. Isto é suficiente para responder a perguntas que nenhum dashboard consegue responder: que parte da fatura corresponde a subagentes em vez das suas próprias interações, se um servidor MCP duplicou os seus tokens de entrada, ou se as leituras da cache diminuíram depois de alguém editar CLAUDE.md. O comportamento da cache é normalmente onde surgem as surpresas, e quando o caching de prompts compensa explica o que está a analisar.

Vale a pena fazer uma correção, porque este ponto surge em todas as discussões sobre o assunto. O Langfuse é um bom backend de tracing self-hosted, e a sua execução numa VPS é abordada em self-hosting do Langfuse para tracing de agentes. O endpoint OTLP aceita apenas traces. O Claude Code exporta métricas e eventos de log, não spans, portanto apontar OTEL_EXPORTER_OTLP_ENDPOINT para o Langfuse deixa o projeto vazio e não produz nenhum erro útil. O Langfuse é a ferramenta certa para agentes que cria através da API, onde o seu próprio código cria cada span com o respetivo prompt, modelo e custo. Para o CLI do Claude Code, uma base de dados de métricas é a opção adequada.

Configurar o acompanhamento de custos do Claude Code no seu próprio VPS

Bastam dois serviços: um coletor para receber as métricas e o Prometheus para as armazenar. Mantenha ambos fora da Internet pública, porque uma porta OTLP aberta aceita escritas de qualquer pessoa que a encontre. Escreva /opt/ccmetrics/compose.yaml:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 é o endereço do servidor dentro de um túnel WireGuard. Assim, o coletor fica acessível a partir das suas máquinas e de nenhum outro local. O endereço colocado antes da porta é importante porque as portas Docker publicadas não são filtradas pelo ufw: consulte por que as portas publicadas pelo Docker ignoram o ufw. A configuração do próprio túnel está descrita em uma VPN WireGuard no seu próprio VPS.

/opt/ccmetrics/collector.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml. A porta 8889 nunca é publicada no host, porque o Prometheus acede ao coletor através da rede Compose, usando o nome do serviço:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

O log do coletor deve terminar com Everything is ready. Begin running and processing data.. Se o log parar devido a um erro de configuração, o YAML não foi analisado corretamente e o contentor será reiniciado continuamente.

Agora aponte o Claude Code para o coletor. Em cada máquina que executa o Claude Code, adicione isto a ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

Inicie uma sessão, envie um prompt, aguarde o intervalo de exportação (10 segundos neste caso, 60 segundos por predefinição) e pergunte ao Prometheus o que recebeu:

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

Deverá obter vários nomes que começam por claude_code_. O exportador substitui os pontos por sublinhados e acrescenta a unidade, pelo que as cadeias exatas dependem da versão do seu coletor. Um resultado vazio significa que nada chegou. Confirme que o protocolo e a porta correspondem, porque http/protobuf usa a porta 4318 e grpc usa a porta 4317. Uma incompatibilidade falha silenciosamente. Execute claude --debug para que o log de depuração apresente os erros de exportação do OTel.

Para uma única máquina e sem servidor, ignore tudo o que foi descrito acima. Defina OTEL_METRICS_EXPORTER=prometheus e o Claude Code expõe diretamente um endpoint de recolha em http://localhost:9464/metrics. Quando prometheus é o único exportador listado, o Claude Code omite as unidades USD, tokens e s dos nomes das métricas, para manter a recolha num formato de texto Prometheus válido.

Esta arquitetura envolve uma decisão de privacidade. Por predefinição, apenas os contadores saem da máquina; o texto dos prompts e a saída das ferramentas não são enviados. OTEL_LOG_USER_PROMPTS=1 e OTEL_LOG_TOOL_CONTENT=1 alteram esse comportamento. Nesse caso, a caixa de métricas passa a conter código-fonte e qualquer outro conteúdo presente no contexto. Ative essas opções deliberadamente e leia primeiro manter segredos fora do contexto do agente.

Acompanhar os custos de execuções por script e CI

As execuções não interativas são as que mais surpreendem, porque ninguém está a monitorizar o ecrã. claude -p com --output-format json apresenta o custo dessa execução no payload do resultado:

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

O payload inclui total_cost_usd e uma discriminação por modelo. Assim, um job de CI pode registar o seu próprio custo sem utilizar um dashboard. Anexe o valor a um ficheiro ou envie-o como métrica para o coletor acima. Esta é a forma mais económica de acompanhar custos de forma útil e requer uma chamada jq por execução.

Modos de falha e o que verá

O relatório está vazio. npx ccusage@latest daily não apresentar linhas significa que não está a ler o local onde o Claude Code escreve. CLAUDE_CONFIG_DIR altera esse local, e é necessário indicar essa localização ao analisador. Se existirem linhas, mas terminarem cerca de um mês antes, isso significa que cleanupPeriodDays está a funcionar conforme previsto: por predefinição, as transcrições são removidas após 30 dias.

Duas máquinas apresentam totais diferentes. É esperado e não é um erro. Tanto /usage como qualquer analisador de logs leem apenas o histórico de sessões local. Por isso, a utilização de outro dispositivo ou do claude.ai não aparece em nenhum dos dois.

O total local não coincide com a fatura. Os valores locais são calculados a partir das contagens de tokens, usando as tarifas de tabela padrão. Não têm informação sobre preços promocionais ou descontos contratados. Numa subscrição, os tokens nem sequer são faturados individualmente. A página de utilização da Console é a fonte oficial para a faturação da API.

O custo aumentou embora tenha feito o mesmo trabalho. Verifique primeiro as colunas de cache. Uma sessão longa reenvia todo o seu histórico a cada interação. Enquanto a cache está ativa, é aplicada a tarifa de cache. Quando a cache expira, é aplicada a tarifa total de entrada. Assim, uma pausa longa faz com que toda a conversa seja processada novamente. Isto aparece como um valor de entrada elevado junto de um valor de saída reduzido. a tarifação de tokens de entrada e saída explica por que razão os dois valores variam de forma independente.

Um dia com subagentes parece impossível. Cada subagente utiliza a sua própria janela de contexto. Por isso, o consumo de tokens aumenta conforme o número de subagentes executados e a duração de cada execução. Apenas os dados OTel os distinguem, através do atributo query_source em claude_code.token.usage. Um analisador de logs apresenta o total, mas não permite identificar a origem dos valores.

FAQ

O ccusage mostra o que realmente me é cobrado num plano Max?

Não. Numa subscrição, não é cobrado um valor por token. Por isso, um analisador de logs calcula o preço dos seus tokens com as tarifas padrão publicadas da API e mostra quanto o mesmo trabalho teria custado através da API. É uma boa medida relativa da carga de um dia e é útil para comparar projetos ou modelos entre si. Para saber o valor efetivamente devido, a página de utilização do Console mostra a faturação da API e a página de faturação do plano mostra a faturação da subscrição.

Onde é que o Claude Code armazena os ficheiros de sessão lidos por estas ferramentas?

Em ~/.claude/projects/<project>/<session-id>.jsonl, onde <project> é o caminho do diretório de trabalho com os caracteres não alfanuméricos substituídos por -. Cada linha é um objeto JSON correspondente a uma mensagem, utilização de uma ferramenta ou entrada de metadados. CLAUDE_CONFIG_DIR move o diretório completo, e cleanupPeriodDays em settings.json controla a retenção de 30 dias. A Anthropic documenta o formato das entradas como interno e sujeito a alterações entre versões. Por isso, analise-o com uma ferramenta mantida, em vez de usar o seu próprio script.

Posso enviar a telemetria do Claude Code para o Langfuse?

Não diretamente. O endpoint OTLP do Langfuse aceita traces, enquanto o Claude Code exporta métricas e eventos de log, e não spans. Por isso, não existe um destino compatível para esses dados. Envie as métricas do Claude Code para um coletor OpenTelemetry e armazene-as no Prometheus. Use o Langfuse para agentes que constrói na própria API, onde o seu código emite spans que incluem o prompt, o modelo e o custo.

Porque é que os meus valores locais não coincidem com a página de utilização do Console?

Porque são calculados de forma diferente. /usage e os analisadores de logs somam as contagens de tokens dos ficheiros de sessão na máquina que está a utilizar e calculam o preço com as tarifas padrão publicadas. O Console mostra o valor efetivamente cobrado à sua organização, em todas as máquinas e todas as chaves, depois de aplicar eventuais descontos. Uma divergência é normal. Uma divergência muito grande normalmente significa que existe um segundo dispositivo, um executor de CI ou outro membro da equipa a faturar na mesma conta.

Como acompanho o custo de uma execução claude -p na CI?

Execute-a com --output-format json e leia total_cost_usd no resultado, por exemplo com claude -p "..." --output-format json | jq '.total_cost_usd'. O mesmo payload inclui uma discriminação por modelo e o ID da sessão. Registe esse valor por job para obter a despesa por pipeline sem um agente, dashboard ou serviço adicional.