ccusage - Ferramenta de análise de uso do Claude Code

Projeto Visão Geral

ccusage é uma ferramenta CLI para analisar dados de uso de arquivos JSONL locais do Claude Code. O projeto foi desenvolvido por @ryoppippi, inspirado por um artigo sobre o rastreamento dos custos de uso do Claude Code.

Principais Características

📊 Vários Tipos de Relatório

• Relatório Diário: Resume o uso de tokens e o custo por data
• Relatório Mensal: Resume o uso de tokens e o custo por mês
• Relatório de Sessão: Exibe o uso agrupado por sessão de conversa
• Relatório de Blocos de 5 Horas: Relatório baseado em janelas de faturamento de 5 horas
• Linha de Status: Linha de status compacta para hooks (Beta)

🎯 Poderosas Funções de Filtragem e Análise

• Filtragem por Data: Filtra relatórios por intervalo de datas usando --since e --until
• Análise de Projeto: Agrupa por projeto/instância, suporta filtragem de projeto específico
• Detalhamento de Custo por Modelo: Detalhamento de custo para cada modelo
• Fuso Horário e Localização: Suporta fuso horário UTC e formato de localização japonês

🎨 Saída e Exibição Atraentes

• Exibição em formato de tabela colorida, com layout responsivo automático
• Tabela Inteligente: Terminais estreitos (<100 caracteres) alternam automaticamente para o modo compacto, exibindo colunas essenciais
• Modo Compacto: Força o layout de tabela compacta usando a flag --compact, ideal para capturas de tela e compartilhamento
• Exibição de Modelo Aprimorada: Nomes de modelos exibidos como listas com marcadores, melhorando a legibilidade

💰 Funções de Rastreamento de Custo

• Exibe custos diários/mensais/de sessão em USD
• Suporte a tokens em cache: Rastreia e exibe separadamente os tokens de criação de cache e de leitura de cache
• Modo offline: Use --offline para usar dados de preços pré-armazenados em cache sem conexão de rede (apenas modelos Claude)

⚡ Monitoramento em Tempo Real

• Painel de uso em tempo real
• Monitoramento em tempo real: ccusage blocks --live

Instalação e Uso

Início Rápido (sem necessidade de instalação)

Devido ao tamanho de pacote extremamente pequeno do ccusage, ele pode ser executado diretamente sem instalação:

# Usando bunx (recomendado, mais rápido)
bunx ccusage

# Usando npx
npx ccusage@latest

# Usando deno (com flags de segurança)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

Instalação Global

# Instalar globalmente com npm
npm install -g ccusage

# Instalar globalmente com bun
bun install -g ccusage

# Em seguida, execute
ccusage

Ambiente de Desenvolvimento

# Clonar o repositório
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Instalar dependências
bun install

# Executar a ferramenta
bun run report [subcommand] [options]

Uso Básico

Relatório Diário

# Mostrar todo o uso diário
ccusage daily

# Filtrar por intervalo de datas
ccusage daily --since 20250525 --until 20250530

# Usar diretório de dados Claude personalizado
ccusage daily --path /custom/path/to/.claude

# Saída em formato JSON
ccusage daily --json

# Detalhamento de custo por modelo
ccusage daily --breakdown

# Usar fuso horário UTC
ccusage daily --timezone UTC

# Usar localização japonesa
ccusage daily --locale ja-JP

Análise de Projeto

# Agrupar por projeto/instância
ccusage daily --instances

# Filtrar para um projeto específico
ccusage daily --project myproject

# Combinar uso
ccusage daily --instances --project myproject --json

Relatório de Sessão

# Mostrar todas as sessões
ccusage session

# Filtrar sessões pela data da última atividade
ccusage session --since 20250525

# Combinar filtros
ccusage session --since 20250525 --until 20250530 --path /custom/path

# Saída em formato JSON
ccusage session --json

Monitoramento em Tempo Real

# Painel de uso em tempo real
ccusage blocks --live

# Janela de faturamento de 5 horas
ccusage blocks

# Linha de status (Beta)
ccusage statusline

Modo Compacto

# Forçar modo de tabela compacta
ccusage --compact

# Relatório mensal compacto
ccusage monthly --compact

Opções de Comando

Todos os comandos suportam as seguintes opções:

• -s, --since <date>: Filtrar a partir da data (formato YYYYMMDD)
• -u, --until <date>: Filtrar até a data (formato YYYYMMDD)
• -p, --path <path>: Caminho personalizado para o diretório de dados do Claude (padrão: ~/.claude)
• -j, --json: Exibir resultados em formato JSON em vez de tabela
• -h, --help: Exibir informações de ajuda
• -v, --version: Exibir versão

Exemplos de Saída

Saída do Relatório Diário

╭──────────────────────────────────────────╮
│                                          │
│ Relatório de Uso de Tokens do Claude Code - Diário │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ Data             │ Tokens de Entrada │ Tokens de Saída │ Total de Tokens │ Custo (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ Total            │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

Saída do Relatório de Sessão

╭───────────────────────────────────────────────╮
│                                               │
│ Relatório de Uso de Tokens do Claude Code - Por Sessão │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ Projeto / Sessão             │ Tokens de Entrada │ Tokens de Saída │ Total de Tokens │ Custo (USD) │ Última Atividade │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ Total                        │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

Arquitetura Técnica

Requisitos de Dependência

• Runtime Bun
• Arquivos de histórico de uso do Claude Code (~/.claude/projects/**/*.jsonl)

Estrutura do Projeto

ccusage/
├── commands/
│   ├── daily.ts        # Comando de relatório diário
│   └── session.ts      # Comando de relatório de sessão
├── data-loader.ts      # Lógica de carregamento de dados JSONL
├── index.ts           # Ponto de entrada CLI
├── logger.ts          # Configuração de log
├── utils.ts           # Utilitários compartilhados
└── package.json

Desenvolvimento e Teste

# Executar testes
bun test

# Verificação de tipo
bun run typecheck

# Análise de código (linting)
bun run lint

# Formatar código
bun run format

Funções de Integração

🔌 Integração MCP

Servidor de Protocolo de Contexto de Modelo (MCP) integrado para integração com outras ferramentas

Resumo

ccusage é uma ferramenta CLI poderosa e fácil de usar, projetada especificamente para usuários do Claude Code, para analisar e rastrear o uso de tokens e os custos associados. Seu design leve, conjunto rico de recursos e saída atraente a tornam uma escolha ideal para desenvolvedores que buscam otimizar o uso do Claude Code e gerenciar custos.