Token Meter

Painel local e servidor MCP para rastreamento de uso de tokens no Claude Code e Codex.

Documentação

Token Meter

Acompanhe o uso e o custo de tokens do Claude Code, Codex e Cursor localmente — sem conta, sem nuvem.

Um painel local para o uso de tokens do seu Claude Code e Codex. Gratuito, compatível com MCP, núcleo com licença MIT.

npm: @whdrnr2583/token-meter · GitHub: whdrnr2583-cmd/token-meter · Site: token-meter.dev

O Token Meter analisa os arquivos JSONL que o Claude Code e o Codex já gravam em disco e os transforma em um painel real: custo por projeto, por modelo, por ferramenta MCP, por hora. Seus dados nunca saem da sua máquina.

Execute sua primeira auditoria

npx -y @whdrnr2583/token-meter audit

Examina seu histórico ingerido do Claude Code + Codex em busca de sessões caras, respostas de ferramentas superdimensionadas, ferramentas lentas, chamadas repetidas e desperdício de cache, classificados por custo e confiança. Funciona inteiramente contra seu banco de dados SQLite local — mesmo processamento local-first, sem nuvem, como o restante do Token Meter. Adicione --json para saída legível por máquina; consulte docs/audit.md para a lista completa de flags e o esquema JSON.

Quando usar isso

Use o Token Meter se você:

quiser saber quantos tokens e dólares suas sessões do Claude Code ou Codex estão custando — detalhado por projeto, modelo e ferramenta MCP
estiver em um plano de taxa fixa (Claude Max, etc.) e quiser ver qual seria o custo equivalente da API
quiser descobrir qual servidor ou ferramenta MCP está consumindo mais tokens, ou qual hora do dia é mais cara
quiser retomar uma sessão recente e precisar do comando claude --resume / codex resume à mão
quiser tudo isso offline, sem conta e sem enviar nada

Não é adequado se você precisar de números de nível de faturamento validados contra sua fatura da Anthropic ou OpenAI — o Token Meter calcula estimativas apenas a partir dos arquivos JSONL locais.

Ferramentas MCP

Quando o Token Meter é configurado como servidor MCP (install-mcp all), quatro ferramentas ficam disponíveis para seu assistente de IA:

Ferramenta	O que retorna
`usage_summary`	Tabela diária de contagens de tokens, custo equivalente em USD e contagens de chamadas — detalhada por dia e modelo
`recent_sessions`	Sessões mais recentes com comandos `claude --resume` / `codex resume` prontos para colar
`session_tools`	Detalhamento por ferramenta dentro de uma sessão: contagem de chamadas, total de tokens, latência média, tamanho da resposta
`refresh_data`	Reexamina seus logs JSONL locais em busca de nova atividade e retorna um resumo atualizado

Todas as quatro são somente leitura. Nenhum dado sai da sua máquina.

Exemplos de prompts

Copie e cole qualquer um destes no Claude Code ou Cursor após instalar o servidor MCP:

Show me my token usage and cost for the last 7 days.

List my recent sessions so I can pick one to resume.

Show the tool breakdown for my most recent session — which tool used the most tokens?

Refresh token-meter data, then tell me which model cost the most this week.

Which hour of the day am I spending the most tokens on?

Início rápido

npx @whdrnr2583/token-meter ingest        # scan ~/.claude/projects + ~/.codex/sessions
npx @whdrnr2583/token-meter stats 30      # CLI summary for last 30 days
npx @whdrnr2583/token-meter serve         # http://localhost:8765 dashboard
npx @whdrnr2583/token-meter mcp           # run as an MCP server for Claude Code / Cursor

O pacote é publicado sob um escopo npm (@whdrnr2583/) porque o nome simples token-meter colide com um nome semelhante existente no npm. O binário CLI ainda é chamado de token-meter após a instalação.

Conecte o Token Meter à sua ferramenta de IA (MCP)

Um comando registra o Token Meter em todos os clientes compatíveis na sua máquina:

npx -y @whdrnr2583/token-meter install-mcp all

Gerencia Claude Code, Cursor e Claude Desktop — idempotente, faz backup da configuração existente, preserva outros servidores MCP. Variantes de cliente único: install-mcp claude-code | cursor | claude-desktop. Adicione --dry-run para visualizar.

Ou deixe seu LLM fazer isso. Abra o Claude Code / Cursor / Claude Desktop e peça: "Leia https://raw.githubusercontent.com/whdrnr2583-cmd/token-meter/main/docs/mcp-server.md e configure o token-meter como meu servidor MCP."

Comandos manuais de uma linha (se preferir não executar nosso instalador):

Cliente	Comando / configuração
Claude Code	`claude mcp add token-meter -- npx -y @whdrnr2583/token-meter mcp` e depois `claude mcp list` para verificar
Cursor	Edite `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`) — veja docs/mcp-server.md
Claude Desktop	Edite `claude_desktop_config.json` — veja docs/mcp-server.md
ChatGPT	Somente stdio por enquanto; receita de wrapper HTTP em docs/mcp-server.md
Outros (Continue, Zed, personalizado)	`npx -y @whdrnr2583/token-meter mcp` via stdio

Depois, peça: "Use o token-meter para mostrar minhas sessões recentes" ou "Use o token-meter usage_summary para esta semana".

Atalho do Claude Code: execute npx -y @whdrnr2583/token-meter install-command claude-code uma vez para registrar o comando de barra /token-meter. Após reabrir sua sessão, digite /token-meter para um resumo rápido sem linguagem natural.

Configuração completa + verificação + solução de problemas: docs/mcp-server.md.

Armazenamento: ~/.tokenpulse/usage.db (SQLite). Remova a pasta para recomeçar. O nome da pasta se tornará ~/.tokenmeter/ em uma versão futura com uma migração automática; até lá, o diretório v0.1 mantém seu nome original.

O que você vê

Custo equivalente em USD por dia, modelo, projeto. Útil se você estiver em um plano Max e quiser saber quanto a API teria custado.
Detalhamento de MCP e ferramentas: qual servidor MCP está consumindo tokens, quão lenta cada ferramenta é em média, tamanhos de resposta por chamada.
Distribuição horária de tokens de saída.
Claude Code + Codex lado a lado, em uma única visualização.

Uma nota sobre os valores em dólar

Os custos são estimativas calculadas localmente a partir das contagens de tokens que o Claude Code e o Codex já gravam em seus arquivos JSONL, multiplicadas pela taxa publicada por milhão de tokens do modelo. Eles não são validados contra sua fatura real da Anthropic / OpenAI e podem divergir por vários motivos:

Os fornecedores mudam os preços; a tabela em src/pricing.ts é um instantâneo
Planos de assinatura (Pro / Max) cobram uma taxa fixa — o $ na tela é o que a API teria custado, não o que você paga
Algumas categorias de tokens (uso de ferramentas no servidor, variantes de gravação de cache) são aproximadas

Trate os números como sinal relativo para identificar desperdício, não como contabilidade de nível de faturamento. O Token Meter inclui um teste de regressão que garante que o cálculo seja reproduzível, e um script de auditoria que verifica invariantes; nenhum deles verifica as taxas contra faturas de fornecedores.

Por que local-first

Seu JSONL contém código-fonte, prompts e resultados de ferramentas. O Token Meter nunca envia nada disso. Apenas heurísticas, regex e agregação SQL.
Sem SDK para integrar, sem proxy para configurar no nível gratuito.
O CLI e o núcleo do painel são licenciados sob MIT.

Preços

Nível	Preço	O que você obtém
Gratuito	$0	Análise do Claude Code + Codex, detalhamento MCP/ferramentas, detalhamento por hora/modelo/projeto, histórico de 7 dias, 1 alerta de desktop
Pro	$5/mês	Tudo do Gratuito, reformulado como uma revisão mensal de gastos: histórico de 30 dias (este mês vs. o anterior), detalhamento por sessão/mensagem até a execução que estourou o orçamento, dólares economizados com eficiência de cache, sinais de desperdício (respostas de ferramentas superdimensionadas + cache que não compensou), além de alertas inteligentes ilimitados (desktop + webhook)
Pro+	em breve	Proxy LLM local (Ollama / LM Studio / llama.cpp / vLLM), rastreamento de GPU/VRAM, ações automáticas

Pro é a diferença entre olhar o número da semana passada e revisar onde o gasto do mês vazou. Pro está disponível — Assine em token-meter.dev.

O Pro+ será lançado quando as inscrições do Pro + a demanda da comunidade confirmarem o segmento.

Roadmap

M1 ✅ Análise do Claude Code, detalhamento MCP/ferramentas, estatísticas horárias
M2 ✅ Integração com Codex
M3 Nível Pro ($5), faturamento Polar.sh, ativação de licença
M4+ Pro+ (proxy LLM local, rastreamento de GPU), condicionado à demanda

Privacidade e segurança

Os tokens são contados a partir dos arquivos JSONL que o Claude Code e o Codex já gravam. O Token Meter não toca nas APIs de rede de nenhum dos fornecedores.
Nenhum corpo de prompt ou resposta é armazenado por padrão — apenas metadados (carimbos de data/hora, contagens de tokens, nomes de ferramentas, comprimentos de resposta).
O banco de dados fica em ~/.tokenpulse/; exclua-o para apagar tudo. (Renomeado para ~/.tokenmeter/ em uma versão futura com uma migração automática.)

Changelog

Veja CHANGELOG.md para notas de versão e mudanças que quebram compatibilidade.

Licença

MIT para o CLI, painel e analisadores. Recursos do nível Pro são distribuídos em um pacote separado sob uma licença de código fechado.