token-tracker

token-tracker

Plugin para Claude Code que acumula, por projeto, os tokens consumidos e os custos em USD de cada sessão. Mantém histórico diário e gera gráficos ASCII (no terminal) e HTML interativo (no navegador).

Por que existe

O /cost nativo do Claude Code mostra o gasto da sessão atual, mas perde tudo quando você fecha. Este plugin persiste os números no próprio projeto e separa por modelo, então você consegue responder perguntas como:

• Quanto já gastei neste projeto até hoje?
• Qual modelo está consumindo mais? Sonnet ou Opus?
• Como está a curva diária? Estou virando um cliente caro?

Instalação (via marketplace)

Dentro do Claude Code:

/plugin marketplace add eduardovrocha/token-tracker
/plugin install token-tracker@token-tracker

Reinicie o Claude Code (/exit e abra de novo). Pronto — o hook vai disparar no fim de cada sessão.

Substitua eduardovrocha pelo seu usuário do GitHub se forkou o repo.

O que é coletado

Quando uma sessão termina (com /exit, /clear ou compactação), o hook lê o transcript da sessão (JSONL local que o Claude Code já mantém) e soma:

• input_tokens e output_tokens por modelo
• cache_creation_input_tokens e cache_read_input_tokens por modelo
• Custo em USD calculado pela tabela em scripts/pricing.py

Os dados ficam em dois arquivos por projeto:

<seu-projeto>/.claude/token-usage.json        # totais acumulados + breakdown por modelo + últimas 100 sessões
<seu-projeto>/.claude/token-usage-daily.json  # série diária (alimenta os gráficos)

Adicione ambos ao .gitignore do projeto.

Comandos

Comando	O que faz
/tokens	Resumo formatado: totais, custo, breakdown por modelo
/tokens-chart	Gráfico ASCII (USD por dia + tokens por dia) no terminal
/tokens-chart-html	Gera .claude/token-usage.html com Chart.js e abre no browser

Preços usados (USD por milhão de tokens)

Modelo	Input	Output	Cache write	Cache read
Opus 4.7 / 4.6	5.00	25.00	6.25	0.50
Sonnet 4.6 / 4.5	3.00	15.00	3.75	0.30
Haiku 4.5	1.00	5.00	1.25	0.10

Fonte: claude.com/pricing. Verificado em 09/05/2026. Edite plugins/token-tracker/scripts/pricing.py quando os preços mudarem.

Como funciona por baixo

Hooks do Claude Code não recebem usage de tokens diretamente no payload (ainda — veja issue #11008). Em vez disso, recebem o transcript_path da sessão. O plugin abre esse JSONL, percorre as mensagens do assistant (filtrando summary, isSidechain e isApiErrorMessage) e soma o message.usage de cada uma.

Esse é o mesmo método usado por ferramentas como ccusage e por extensões de monitoramento de IDE.

Estrutura do repositório

.claude-plugin/
  marketplace.json              # catálogo do marketplace
plugins/
  token-tracker/
    .claude-plugin/plugin.json  # manifest
    hooks/
      hooks.json                # registra SessionEnd
      session-end.py            # lê transcript, calcula, persiste
    scripts/
      pricing.py                # tabela de preços
      chart.py                  # gráfico ASCII
      chart_html.py             # gráfico HTML
    commands/
      tokens.md
      tokens-chart.md
      tokens-chart-html.md

Requisitos

• Claude Code 2.x ou superior
• Python 3.9+ (já vem no macOS/Linux; o plugin usa só stdlib)

Desenvolvimento local

Para testar mudanças sem publicar:

git clone https://github.com/eduardovrocha/token-tracker
cd token-tracker
# adicione o caminho local como marketplace
claude
> /plugin marketplace add ./
> /plugin install token-tracker@token-tracker

Licença

MIT — veja LICENSE.