O que é ccusage?
O ccusage lê os logs de uso que o Claude Code e outras CLIs de agentes guardam na sua máquina e informa tokens e custo estimado por dia, semana, mês ou sessão. Para o Claude Code, também mostra os blocos de cobrança de 5 horas com uma visão ao vivo e oferece uma statusline compacta (em beta) para a barra de status do Claude Code.
Ele roda com `npx ccusage@latest` (ou bunx, pnpm dlx, Nix) e não exige conta nem chave de API. O README lista 18 fontes, incluindo Claude Code, Codex, OpenCode, Amp, Goose, Kilo, Gemini CLI e GitHub Copilot CLI. Os preços vêm do LiteLLM, do models.dev e de tabelas históricas embutidas, guardados em cache local, com um modo `--offline`.
ccusage vale a pena?
O ccusage virou o medidor local padrão de uso de agentes de programação. Tem cerca de 19,100 estrelas no GitHub, o npm contou aproximadamente 871,000 downloads nos 30 dias até 18 de outubro de 2026, e sai quase todo dia: da v20.0.34 em 15 de outubro à v20.0.41 em 22 de outubro. Criado por ryoppippi, agora fica sob uma organização ccusage, e o código é em Rust, ainda distribuído pelo npm.
A coluna de custo exige leitura cuidadosa. No modo auto padrão, ele usa o costUSD que o Claude Code armazena quando existe e, caso contrário, multiplica os tokens pelos preços por token publicados. A documentação diz claramente que os custos "podem não refletir a cobrança real" e que chamadas de ferramentas como busca na web não entram. Em uma assinatura Pro ou Max, o número não é sua fatura; é o que o mesmo trabalho teria custado com preços pay-as-you-go.
O limite menos óbvio é o histórico. O Claude Code guarda transcrições locais por 30 dias por padrão (a configuração cleanupPeriodDays), e o ccusage só consegue contar o que ainda está em disco. Quem quiser a tendência de um trimestre precisa aumentar essa configuração antes, ou exportar snapshots `--json` de forma agendada.
Os dados de uso nunca saem da máquina, segundo a documentação, mas por padrão o ccusage atualiza seu cache de preços pela rede; `--offline` impede isso. Os relatórios separam tokens de entrada, saída, criação de cache e leitura de cache por modelo, que é o detalhamento necessário para saber se uma mudança no prompt caching ou um plugin de economia de tokens realmente ajudou.
O escopo é uma máquina. Não há servidor nem visão de equipe documentados, então um gestor comparando dez desenvolvedores precisa juntar e somar dez arquivos JSON à mão, e cada um só é tão completo quanto a retenção de logs daquele laptop.
Onde ele se destaca
Um desenvolvedor testando um plugin de economia de tokens como o RTK
Provar se ele realmente reduz o uso
Rodar `ccusage daily --json` por uma semana antes e uma semana depois de instalá-lo e comparar tokens de entrada e de leitura de cache por modelo. Leva minutos e não custa nada; a comparação só é justa se as cargas das duas semanas forem parecidas.
Um gerente de engenharia que paga assentos do Claude Max
Decidir se passar a equipe para cobrança via API sairia mais barato
Cada desenvolvedor roda `ccusage monthly --json` e compartilha o arquivo; os totais mostram quanto o mesmo uso custaria com preços de API. Como não há visão compartilhada, juntar e somar os arquivos é manual.
Um desenvolvedor freelancer que cobra vários clientes
Atribuir o gasto com agentes a cada projeto de cliente
`ccusage claude daily --instances --project <name>` agrupa o uso do Claude Code por projeto; o valor equivalente à API é um item de fatura defensável se o contrato cobrar ferramentas a preço de custo.
Antes de decidir
- Configuração
- `npx ccusage@latest` imprime um relatório diário em segundos; o bunx guarda o pacote em cache, então as execuções seguintes são mais rápidas. Adicione `ccusage statusline` ao hook de status line do Claude Code para ter um número ao vivo.
- Integrações
- Lê logs locais de 18 CLIs de agentes, incluindo Claude Code (~/.claude e ~/.config/claude/projects), Codex, OpenCode, Gemini CLI e Copilot CLI; gera tabelas ou JSON; ajustes de preço ficam em ccusage.json.
- Dados e privacidade
- A análise é local e os dados de uso não são enviados, segundo a documentação; os dados de preço são baixados e guardados em cache, a menos que você passe --offline. Licença MIT, então o uso comercial é irrestrito.
- Custo em escala
- Gratuito, sem edição paga; é financiado por patrocinadores. O único custo é o hábito de rodá-lo em cada máquina que você quer contar.
- Limites
- Os valores em dólar são estimativas que excluem busca na web; o Claude Code apaga as transcrições após 30 dias, a menos que cleanupPeriodDays seja aumentado; sem agregação de equipe. Só 4 issues abertas na última verificação.
O que é bom
- Relatórios totalmente locais, sem conta
- 18 CLIs de agentes em um relatório
- Separa tokens de criação e de leitura de cache por modelo
- Visão de blocos de 5 horas, statusline e saída --json
O que não é
- Os custos são estimativas equivalentes à API e excluem busca na web
- Histórico limitado ao que o agente guarda em disco (30 dias no Claude Code por padrão)
- Sem modo de equipe ou servidor
Ideal para
Quem quer acompanhar ou comparar o uso de tokens entre sessões de agentes.
Alternativas ao ccusage
ccusage: perguntas frequentes
- ccusage vale a pena?
- O ccusage é o medidor que todo usuário intenso de agentes deveria rodar, desde que leia a coluna de dólares como o que o trabalho teria custado na API, não como o que pagou. Damos nota 4.4 de 5.
- Quanto custa ccusage?
- Gratuito e de código aberto (MIT).
- Quais são as desvantagens de ccusage?
- Os custos são estimativas equivalentes à API e excluem busca na web; histórico limitado ao que o agente guarda em disco (30 dias no Claude Code por padrão); sem modo de equipe ou servidor.
- Para quem ccusage é indicado?
- Quem quer acompanhar ou comparar o uso de tokens entre sessões de agentes.
- Quanto custa ccusage para uma equipe ou em produção?
- Gratuito, sem edição paga; é financiado por patrocinadores. O único custo é o hábito de rodá-lo em cada máquina que você quer contar.
- ccusage é seguro para dados da empresa?
- A análise é local e os dados de uso não são enviados, segundo a documentação; os dados de preço são baixados e guardados em cache, a menos que você passe --offline. Licença MIT, então o uso comercial é irrestrito.
- Quais são as melhores alternativas ao ccusage?
- As alternativas mais próximas que analisamos são rtk (Rust Token Killer), Claude Code Router e mindwalk.
Respostas verificadas em 23 de out. de 2026.