Ferramentas para rastrear gastos do Claude Code

O que um rastreador de custos do Claude Code lê efetivamente

Todos os rastreadores de custos do Claude Code leem uma de três fontes de dados, e a fonte determina a pergunta que 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 contabilizam coisas diferentes.

Este guia não explica novamente os tokens. como o Claude Code contabiliza a utilização de tokens descreve os tokens de entrada e saída, as escritas na cache e as leituras da cache, e nenhum dashboard fará muito sentido até essa parte estar 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 custos do Claude Code no mesmo dia

Três rastreadores de custos distintos 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 encapsulava os ecrãs de utilização da conta. O terceiro era um backend de rastreio alojado que o utilizador executa por conta própria.

Surgiram em conjunto porque o custo de uma sessão de agente deixou de ser evidente. Um chat custa aproximadamente o que é possível ver no ecrã. Um agente lê vinte ficheiros, executa o conjunto de testes e reenvia toda a conversa a cada interação. Por isso, a fatura é determinada por contexto que o utilizador nunca introduziu. Numa subscrição, não existe sequer um valor em dólares. Existe apenas uma barra de utilização que se esvazia mais depressa em alguns dias do que noutros. Cada uma das três abordagens preenche uma parte diferente dessa lacuna.

Forma 1: um analisador de logs local mostra quanto custou o dia

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

ccusage é a opção que a maioria das pessoas acaba por usar. 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. É assim que 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 é reiniciada. session calcula os totais por conversa, e --instances agrupa-os por projeto para mostrar qual repositório é mais dispendioso. Adicione --since e --until para limitar o intervalo, e execute npx ccusage@latest daily --help para ver 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. Isso é útil se estiver a compará-los.

Os preços vêm de uma tabela de preços dos modelos, e a ferramenta tem três modos de cálculo de custos. --mode auto usa o valor costUSD escrito pelo Claude Code no ficheiro, quando este existe, e calcula o valor a partir das contagens de tokens quando não existe. --mode calculate calcula sempre o valor 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 um custo registado. Nesse caso, tudo o que está a ler é uma estimativa.

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 analisador 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. Os dados antigos também desaparecem, porque as transcrições são limpas por predefinição após 30 dias através da definição cleanupPeriodDays. Por isso, o trimestre anterior já não está disponível, a menos que o tenha arquivado.

Existe ainda outro risco, de natureza estrutural. A documentação da Anthropic afirma que o formato das entradas é interno ao 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 por essa razão que um one-liner jq escrito manualmente sobre o JSONL é uma opção pior do que parece: os analisadores mantidos acompanham as alterações de formato, enquanto o seu one-liner apresentará um número errado com toda a 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 paga por token nos planos Pro ou Max. Por isso, o número representa o que os seus tokens teriam custado às tarifas públicas da API. Mede a intensidade do seu uso. Não corresponde à sua fatura. Se a questão real for escolher o plano, essa comparação é um exercício separado: consulte faturação da API em comparação 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 reflete 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.

Nos planos 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. Assinala comportamentos responsáveis por 10% ou mais da utilização recente, como contextos longos 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 desta máquina, pelo que a utilização num segundo dispositivo não é contabilizada.

Quando há mais de um developer, os valores passam para a conta. Uma organização da API tem a página de utilização da Console, um dashboard do Claude Code com os gastos e as linhas aceites por membro, e uma API de Analytics do Claude Code que devolve as mesmas métricas diárias por utilizador com 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, e o Enterprise acrescenta uma API de analytics. O que vê depende da forma como cada developer iniciou sessão. Por isso, uma organização mista consulta dois relatórios e soma 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. Considere isto uma referência publicada com base em implementações empresariais, não uma previsão para a sua equipa. Execute um piloto com um grupo e faça medições antes de extrapolar.

Os dashboards não conseguem ver nada abaixo do nível do dia e da pessoa. Mostrarão que o Opus foi responsável pela maior parte da utilização de terça-feira. Não mostrarão qual prompt, qual repositório ou qual 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 durante esta tarde. Para detetar e controlar esse agente são necessários limites, não relatórios. Esse é o tema de manter os custos dos agentes sob controlo num VPS.

Formato 3: a sua própria stack OpenTelemetry indica 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 abranger: 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 observar.

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 execução num 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. Por isso, apontar OTEL_EXPORTER_OTLP_ENDPOINT para o Langfuse deixa o projeto vazio e não produz um erro útil. O Langfuse é a ferramenta certa para agentes que desenvolve diretamente na API, em que o seu próprio código cria cada span com o prompt, o modelo e o custo. Para o CLI do Claude Code, uma base de dados de métricas é a opção adequada.

Configure o rastreamento de custos do Claude Code no seu próprio VPS

Dois serviços são suficientes: 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 gravações 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, por isso o coletor fica acessível a partir das suas máquinas e de nenhum outro local. O endereço antes da porta é importante neste caso, 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 configure o Claude Code para o utilizar. 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 depois 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 com claude_code_. O exportador substitui os pontos por sublinhados e acrescenta a unidade, por isso 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 utiliza a porta 4318 e grpc utiliza a porta 4317, e uma incompatibilidade falha silenciosamente. Execute claude --debug para que o log de depuração apresente os erros de exportação 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 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 que a recolha continue a utilizar um formato de texto Prometheus válido.

Esta arquitetura envolve uma decisão de privacidade. Por predefinição, apenas as contagens 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 sua caixa de métricas contém código-fonte e tudo o que estivesse 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 observar 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 contém total_cost_usd e uma discriminação por modelo. Assim, um job de CI pode registar o seu próprio custo sem usar um dashboard. Acrescente o valor a um ficheiro ou envie-o como métrica para o coletor acima. Esta é a forma mais económica de obter um acompanhamento útil dos custos e requer uma chamada jq por execução.

Modos de falha e o que será apresentado

O relatório está vazio. npx ccusage@latest daily não apresentar nenhuma linha significa que não está a ler o local onde o Claude Code grava os dados. CLAUDE_CONFIG_DIR altera esse local, e é necessário indicar essa localização ao analisador. Se existirem linhas, mas estas terminarem cerca de um mês atrás, 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, o uso de outro dispositivo ou do claude.ai não aparece em nenhum dos dois.

O total local não corresponde à fatura. Os valores locais são calculados a partir das contagens de tokens, usando as tarifas de tabela padrão. Não consideram preços promocionais nem descontos contratuais. Numa subscrição, os tokens também não são faturados individualmente. A página de utilização do Console é a fonte de informação 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 histórico a cada turno. Enquanto a cache está disponível, é aplicada a tarifa de cache. Quando a cache expira, é aplicada a tarifa de entrada completa. 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 pequeno. os preços dos tokens de entrada e de saída explicam por que motivo os dois valores evoluem de forma independente.

Um dia com subagentes parece impossível. Cada subagente utiliza a sua própria janela de contexto. Por isso, o uso de tokens aumenta com o número de subagentes executados e com 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 e não permite determinar a origem dos valores.

FAQ

O ccusage mostra o que é efetivamente cobrado num plano Max?

Não. Numa subscrição, não é feita uma cobrança por token. Por isso, um analisador de logs calcula o preço dos seus tokens com base nas tarifas padrão da API e mostra quanto o mesmo trabalho teria custado através da API. É uma boa medida relativa da intensidade de um dia e é útil para comparar projetos ou modelos entre si. Para saber o valor que deve pagar, a página de utilização da Console apresenta a faturação da API e a página de faturação do plano apresenta 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 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 um script próprio.

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 desenvolva diretamente na API, nos quais o seu próprio código emite spans com o prompt, o modelo e o custo.

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

Porque são calculados de forma diferente. /usage e os analisadores de logs somam as contagens de tokens dos ficheiros de sessão existentes na máquina que está a utilizar e calculam o preço com base nas tarifas padrão. A Console apresenta o valor efetivamente cobrado à sua organização, em todas as máquinas e com todas as chaves, depois de aplicar eventuais descontos. Uma diferença é normal. Uma diferença 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 no CI?

Execute-a com --output-format json e leia total_cost_usd do 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 o gasto por pipeline sem um agente, dashboard ou serviço adicional.