Veja quanto o Claude Code custa de verdade com o ccusage — e depois decida como pagar
«Achei caro este mês» não é dado. O ccusage lê seus logs locais de sessão e converte pela tabela oficial: um comando para começar, o que o número significa, e o formato de uso que responde assinatura vs. por uso.
Todo usuário de Claude Code tem o mesmo momento de dúvida: exagerei este mês? A dúvida costuma parar no sentimento, porque o próximo passo é constrangedor — assinante não vê fatura, só uma barra de progresso; usuário de API vê fatura, mas só lembra de olhar no fim do mês. A resposta esteve o tempo todo na sua máquina: o Claude Code grava o uso de cada sessão em logs locais, e o ccusage é a ferramenta mais simples para ler esse livro em voz alta. Isto não é outro manual do ccusage — o comando é uma linha e não precisa de manual. É sobre o que vem depois de medir: qual preço o número usa, quais números importam, e como uma semana de medição responde «como eu deveria estar pagando por isso?»
Transparência de início: eu opero o Teapot Router, um gateway de API por uso. Escrever «como decidir entre assinatura e por uso» me interessa obviamente — por isso as quatro primeiras seções não dependem de provedor nenhum e tratam só dos seus números; a parte interessada aparece na última seção, e todo critério lá é público e recalculável.
«Achei caro» não é dado; os logs locais são
Cada sessão do Claude Code é gravada em arquivos JSONL dentro de ~/.claude: quais requisições, quais modelos, quantos tokens de entrada e saída, quanto cache acertado. O log começa no dia da instalação — salvo acidente, suas últimas semanas de uso estão inteiras lá.
O que o ccusage faz é de uma simplicidade desarmante: lê esse log, multiplica por uma tabela de preços e organiza o resultado por dia, semana e sessão. Não uploada nada, não pede chave de API, não muda configuração — não precisa: o livro e a aritmética ficam na sua máquina.
Um comando para começar, três visões que valem conhecer
Sem instalação — npx ccusage daily roda como está. Três visões que valem no dia a dia, cada uma respondendo uma pergunta:
- daily: quanto custou cada dia — responde «que dia queimou»;
- blocks: fatiado em blocos de cobrança de 5 horas — a visão alinhada às janelas de limite da assinatura; mostra onde cai seu trabalho pesado;
- monthly: o mês somado — olhe aqui antes de perguntar «devo mudar a forma de pagar».
Ele calcula em tabela oficial — o passo que todos pulam
O ccusage multiplica pela tabela oficial de preços. Daí uma distinção crucial: se você é assinante, o número não é o que pagou (você paga mensalidade fixa) — é «quanto esse uso custaria em tabela de API», uma régua para medir uso, não uma fatura. Se você usa API, é aproximação da fatura — aproximação porque a precificação de leitura/escrita de cache pode diferir do extrato exato do provedor; o extrato por requisição segue sendo a fonte da verdade.
A distinção não é pedantismo; é a porta da próxima etapa: leia a saída do ccusage como formato de uso, não como fatura, e os números passam a decidir por você.
Rode uma semana; você ganha mais que um total
O total diz se está caro; o formato diz por quê, e se outro modelo de cobrança sairia mais barato. Rode uma semana e retire quatro parâmetros: horas concentradas por dia (a extensão dos seus blocos), intensidade das tarefas (modelo topo ou equilibrado dominando), taxa de acerto de cache (mesmo contexto, acerto contra frio difere uma ordem de grandeza) e o desenho dos picos (constante todo dia, ou dois dias de explosão). Esses quatro servem muito mais que o total mensal, porque as diferenças entre modelos de cobrança se desdobram nesses quatro eixos.
Do formato à decisão: a cara dessa aritmética
Com o formato em mão, assinatura contra por uso deixa de ser torcida e vira multiplicação atribuível: horas por dia × intensidade numa calculadora de custos, sai o mensal por uso, ponha ao lado do preço da assinatura. Abaixo, o por uso economiza; acima, você está pagando preço de uso por fluxo sem teto — o que ainda pode fazer sentido, mas agora é escolha informada.
A parte interessada, dita com franqueza: nossa calculadora e nosso extrato por requisição fazem exatamente isso — tarifas lidas ao vivo do endpoint público de preços, custo de cada requisição consultável e exportável depois. Mas você não precisa de nós: qualquer provedor que ofereça tabela legível por máquina e extrato por requisição faz a mesma aritmética; quem não oferece nenhum dos dois, por mais barata que pareça a tabela, deveria ter «inverificável» contabilizado como custo.
O valor do ccusage não é o comando; é trocar sentimento por formato. Meça uma semana, memorize quatro números: horas, intensidade, acertos, picos. Com esses quatro, qualquer pitch de cobrança — inclusive o nosso — perde o poder de assustar, porque a resposta é uma multiplicação sua.
Perguntas frequentes
O ccusage é grátis? Precisa de internet ou chave de API?
É livre e gratuito. Só lê os logs de sessão em ~/.claude e calcula localmente — nada enviado, nenhuma chave, roda direto via npx sem instalar nada.
Sou assinante — o número é minha fatura?
Não. O assinante vê «esse uso em tabela oficial de API» — uma régua para medir o formato de uso. O que você paga é a mensalidade fixa. O usuário de API vê uma aproximação da fatura; o extrato por requisição do provedor é a fonte exata.
Como difere do /usage nativo do Claude Code?
O /usage mostra o restante e o consumido da janela de limite atual — um medidor do «agora». O ccusage agrega o histórico em visões de dia/mês/bloco. Um cuida do presente, outro do passado — decidir como pagar exige o segundo.