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 custos do Claude Code no mesmo dia

Três rastreadores separados de custos 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 pode executar por conta própria.

Surgiram em conjunto porque o custo de uma sessão de agente deixou de ser evidente. O custo de uma conversa é aproximadamente o que se consegue ver no ecrã. Um agente lê vinte ficheiros, executa a suite de testes e reenvia toda a conversa em cada turno. Por isso, a fatura é determinada pelo contexto que nunca introduziu. Numa subscrição, o valor em dólares da sessão apresentado pelo Claude Code é uma estimativa que a Anthropic diz não ser relevante para a faturação. O valor importante é uma barra de utilização que esvazia mais depressa em alguns dias do que noutros. Cada uma das três ferramentas preenche uma parte diferente dessa lacuna.

Formato 1: um parser de logs local mostra quanto o uso de hoje custou

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 caracteres não alfanuméricos substituídos por -. Cada resposta do assistente nesse ficheiro contém as contagens de tokens do pedido. Um parser de logs soma esses valores 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 totaliza por data. --breakdown divide cada linha por modelo. É assim que identifica que uma tarde com Opus representa a maior parte da semana. blocks agrupa pelo período de cinco horas em que uma subscrição é reposta. session totaliza por conversa e daily --instances agrupa 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 obter o formato de data esperado pela sua versão. Em outubro de 2026, a ferramenta também lê outras CLIs de agentes, incluindo Codex e OpenCode. Isto é útil para as 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 que o Claude Code escreveu no ficheiro, quando esse valor está presente, e calcula o custo a partir das contagens de tokens quando não está. --mode calculate calcula sempre 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 esse valor. 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. Nesse caso, todos os valores apresentados são estimativas. Se paga tarifas contratadas, pricingOverrides em defaults num ficheiro de configuração ccusage.json substitui o preço dos modelos individuais.

Os mesmos dados podem alimentar o seu prompt. ccusage statusline imprime uma linha compacta para a barra de estado do Claude Code, ligada a ~/.claude/settings.json como qualquer outro comando de linha de estado. Consulte criar uma linha de estado 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 outro membro da equipa ficam armazenados nesses outros discos. Os dados antigos também podem estar em falta, porque as transcrições são removidas após 30 dias por predefinição através da definição cleanupPeriodDays. Por isso, o trimestre anterior já não estará 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 isso que um one-liner jq criado 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 irá apresentar um número incorreto com 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. O uso dentro do limite do seu plano Pro ou Max não é faturado por token. Portanto, o valor representa o que os seus tokens teriam custado às tarifas públicas da API. Mede o volume do seu uso. Não corresponde à sua fatura. A exceção são os créditos de utilização: se os ativar, o uso acima do limite do plano é faturado às tarifas padrão da API como um encargo separado, e o claude.ai mostra o valor gasto nesse mês em Settings > Usage. Se a pergunta real for qual plano deve escolher, essa comparação é uma análise separada: consulte faturação da API em comparação com uma subscrição Claude.

Forma 2: os ecrãs de utilização integrados mostram qual foi o modelo que 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. O valor é calculado localmente a partir das contagens de tokens e das tarifas de tabela padrão, exceto se um administrador tiver definido uma tabela modelPricing nas definições geridas. Nesse caso, a linha Total cost indica at your organization's configured rates. Em qualquer dos casos, o valor é uma estimativa que pode diferir da fatura. Nos planos Pro ou Max, a Anthropic informa que esse valor não é relevante para a faturação, porque essa utilização está incluída no plano. Os totais são repostos quando /clear inicia uma nova conversa.

Num plano Pro, Max, Team ou Enterprise baseado em lugares, o mesmo ecrã mostra quanto do limite do plano já utilizou. O Enterprise baseado em utilização não tem um limite incluído que possa esgotar, porque cada token é faturado às tarifas da API. Nestes planos, o ecrã também atribui a utilização recente a skills, subagents, plugins e servidores MCP individuais, como percentagem do total. 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, por isso um segundo dispositivo não é contabilizado. Quando essa barra está vazia, e não apenas baixa, o ecrã informa que a janela fechou, 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 de um developer, os números passam a ser associados à conta. Uma organização da API tem a página de utilização da Console, um dashboard do Claude Code com a despesa e as linhas aceites por membro, e 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 despesas na consola de administração, com exportação CSV e atualização diária. Esse relatório cobre a despesa de créditos de utilização: a utilização dentro do limite do lugar não é medida em dólares. O Enterprise acrescenta uma API de analytics. O que cada utilizador vê depende da forma como cada developer iniciou sessão. Por isso, uma organização mista consulta dois relatórios e soma-os manualmente.

Para dimensionar um orçamento, o valor publicado na documentação de custos da Anthropic em outubro 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 um benchmark publicado a partir de 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 mostrar nada com granularidade inferior ao dia e à pessoa. Indicam que o Opus foi responsável pela maior parte da utilização de terça-feira. Não indicam qual prompt, repositório ou job de CI a causou. Também têm atraso, porque os relatórios da organização são atualizados diariamente. Por isso, servem para análise e revisão, não para detetar um agente descontrolado esta tarde. Para detetar e limitar esse comportamento são necessários limites, não relatórios. Esse é o tema de manter os custos dos agentes sob controlo num VPS.

Forma 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. Os nomes dos servidores MCP que configurou e dos seus próprios subagentes personalizados chegam como custom, a menos que defina OTEL_LOG_TOOL_DETAILS=1, que também adiciona comandos Bash e a entrada das ferramentas aos eventos de ferramentas. Isto é suficiente para responder a perguntas que nenhum dashboard consegue responder: que parte da fatura corresponde aos subagentes, em vez das suas próprias interações; se um servidor MCP duplicou os seus tokens de entrada; e se as leituras da cache diminuíram depois de alguém editar o CLAUDE.md. O comportamento da cache é normalmente onde surge a surpresa, 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. Por predefinição, 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 nenhum erro útil. A exportação de spans existe, mas está em beta e permanece desativada até definir CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 e OTEL_TRACES_EXPORTER. A integração própria do Langfuse com o Claude Code segue outro caminho: um hook Stop, ou um plugin que instala um, lê as transcrições da sessão depois de cada resposta e converte-as em traces. Por isso, partilha as limitações locais de um parser de logs. O Langfuse é a ferramenta certa para agentes que cria na própria API, onde o seu código cria cada span com o prompt, o modelo e o custo. Para obter totais de despesas do CLI do Claude Code, uma store 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 neste caso, porque as portas Docker publicadas não são filtradas pelo ufw: consulte por que as portas Docker publicadas 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 chega 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 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 por 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 se o protocolo e a porta coincidem, porque http/protobuf usa a porta 4318 e grpc usa a porta 4317. Se não coincidirem, a falha ocorre sem uma mensagem clara. Execute claude --debug-file /tmp/claude-debug.log e procure nesse ficheiro linhas [3P telemetry]. É aí que o Claude Code comunica erros de exportação OTel.

Se tiver apenas uma máquina e nenhum 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 das métricas exportadas, para que a recolha continue a produzir um formato de texto Prometheus válido. Os nomes das métricas não mudam. Uma definição que combine exportadores, como otlp,prometheus, mantém as unidades.

Esta configuração envolve uma decisão de privacidade. Por predefinição, apenas contagens e metadados saem da máquina. O texto dos prompts e a saída das ferramentas não são exportados. OTEL_LOG_USER_PROMPTS=1 adiciona o texto dos prompts aos eventos exportados e OTEL_LOG_TOOL_CONTENT=1 adiciona a saída das ferramentas aos spans de trace. Assim, quando exporta qualquer um destes sinais, a sua caixa de telemetria passa a conter código-fonte e qualquer outro conteúdo que estivesse no contexto. Ative estas opções deliberadamente e leia primeiro como manter segredos fora do contexto do agente.

Acompanhar custos de execuções por script e de 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 comunica 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 depender de um dashboard. Como qualquer valor local, este é uma estimativa do lado do cliente. Uma execução que continue uma conversa com --continue ou --resume comunica o total de toda a conversa, incluindo as execuções anteriores. Anexe o valor a um ficheiro ou envie-o como métrica para o coletor indicado acima. Esta é a forma mais barata e útil de acompanhar custos. Requer uma chamada jq por execução.

Modos de falha e o que verá

O relatório está vazio. npx ccusage@latest daily sem linhas 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 parser. Se existirem linhas, mas terminarem cerca de um mês atrás, isso significa que cleanupPeriodDays está a funcionar conforme previsto: por predefinição, os transcripts são removidos após 30 dias.

Duas máquinas apresentam totais diferentes. É esperado e não é um erro. A discriminação de /usage e qualquer parser 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 e das tarifas de tabela padrão, exceto se configurar tarifas contratadas: uma tabela modelPricing nas definições geridas para /usage, ou pricingOverrides para o ccusage. Numa subscrição, o uso dentro do limite do plano não é faturado por token, e apenas são faturados os créditos de uso. A página de uso da Console é a fonte autoritativa para a faturação da API.

O custo aumentou apesar de ter feito o mesmo trabalho. Verifique primeiro as colunas de cache. Uma sessão longa reenvia todo o histórico a cada interação. Enquanto a cache está ativa, é 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 reduzido. a tarifação de tokens de entrada e de saída explica por que motivo os dois valores variam de forma independente.

Um dia com subagents parece impossível. Cada subagent executa a sua própria janela de contexto. Por isso, o uso de tokens aumenta com o número de subagents executados e com a duração de cada um. Num plano, a atribuição de /usage apresenta a percentagem correspondente aos subagents nesta máquina. Para obter detalhes por pedido, os dados OTel separam-nos através do atributo query_source em claude_code.token.usage. Um parser de logs mostra o total, mas não permite identificar a origem desse valor.

FAQ

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

Não. A utilização dentro do limite do plano de uma subscrição não é faturada por token. Por isso, um analisador de logs calcula o preço dos seus tokens com as tarifas de tabela padrão da API e mostra quanto o mesmo trabalho teria custado através da API. É uma boa medida relativa do volume de utilização de um dia. Também é útil para comparar projetos ou modelos entre si. Para saber o valor devido, 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. Se tiver os créditos de utilização ativados, a utilização acima do limite é faturada com as tarifas padrão da API. O claude.ai mostra esse valor em Settings > Usage.

Onde é que o Claude Code guarda 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. 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 com a telemetria predefinida. O endpoint OTLP do Langfuse aceita traces. Por predefinição, o Claude Code exporta métricas e eventos de log, em vez de spans, pelo que não existe um destino compatível para esses dados. A exportação de spans é uma funcionalidade beta que tem de ativar. A integração própria do Langfuse com o Claude Code usa um hook Stop que converte os transcripts das sessões em traces. Para obter totais de custos, envie as métricas do Claude Code para um coletor OpenTelemetry e armazene-as no Prometheus. Use o Langfuse para agentes que desenvolver diretamente sobre a API. Nesse caso, o seu próprio código emite spans com o prompt, o modelo e o custo.

Porque é que os meus valores locais não correspondem à 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. Depois, calculam o preço com as tarifas de tabela padrão, exceto quando estão configuradas tarifas contratadas, através de modelPricing nas definições geridas para /usage ou de pricingOverrides para o ccusage. 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 indica que um segundo dispositivo, um executor de CI ou outro membro da equipa está a faturar na mesma conta.

Como acompanho o custo de uma execução de 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 os custos por pipeline sem um agente, dashboard ou serviço adicional.