Tokenscope

Servidor MCP que permite que agentes de IA analisem o custo da sessão do Claude Code e a atribuição de contexto — uso de tokens, releituras em cache e gravações em cache. Local, somente leitura.

GitHub

Experimente este MCPPatrocinado

Documentação

tokenscope ⏣

Veja quanto sua sessão de codificação com IA realmente custou — e o que está consumindo seu contexto. Um CLI local, somente leitura, que analisa os logs de sessão do Claude Code e mostra para onde vai o dinheiro: saída do modelo vs. contexto sendo reenviado a cada turno (os 60%+ ocultos da maioria das contas).

$ npx @wartzar-bee/tokenscope

  tokenscope ⏣  latest session
  ──────────────────────────────────────────────────────
  Total cost   $868.84   over 967 model turns

  Where the money went
  output (model writing)     ████░░░░░░░░░░░░░░░░░░░░  16%  $137.24
  cache read (re-sent ctx)   ████████████████░░░░░░░░  66%  $577.59
  cache write (new ctx)      ████░░░░░░░░░░░░░░░░░░░░  18%  $153.67

  Context size per turn  (peak 822k · avg 404k · now 822k tokens)
  ▁▁▁▁▁▂▂▂▂▂▂▂▃▃▃▃▃▃▃▄▄▄▄▄▅▅▅▅▅▆▆▆▆▇▇▇▇▇▇█

  Insights
  • Re-sent (cached) context cost $577.59 (66% of spend) — context re-read every turn.
  • Peak context ~822k tokens — /compact or a fresh session would cut per-turn cost.
  • Only 16% of spend is the model's actual output.

(Uma sessão real, preços padrão do Opus. Seus números serão diferentes — os preços são substituíveis.)

Por quê

Codificação agêntica (Claude Code, etc.) gera contas surpresa, e a causa é mundana: conforme a sessão cresce, o contexto inteiro é reenviado a cada turno, então o custo aumenta mesmo quando o modelo escreve pouco. Dashboards existentes mostram totais; tokenscope mostra a atribuição — saída vs. leitura de cache vs. escrita de cache vs. entrada nova, a curva de crescimento do contexto por turno, custo por modelo, gasto de subagentes e quais ferramentas preenchem seu contexto — com insights concretos de "corte isso".

Experimente em 10 segundos (sem precisar de logs do Claude Code)

npx @wartzar-bee/tokenscope --demo

Executa em uma sessão de amostra incluída para que você veja o relatório completo antes de apontá-lo para seus próprios logs — sem configuração, nada para ajustar. (A amostra é sintética, para demonstração.)

Instalar / executar

Sem instalação — executa via npx:

npx @wartzar-bee/tokenscope               # your most recent Claude Code session
npx @wartzar-bee/tokenscope --demo        # a bundled sample session — no logs needed
npx @wartzar-bee/tokenscope --all         # aggregate every session
npx @wartzar-bee/tokenscope <file|dir>    # a specific session .jsonl
npx @wartzar-bee/tokenscope --version     # print the installed version and exit
npx @wartzar-bee/tokenscope --json        # machine-readable
npx @wartzar-bee/tokenscope --share       # privacy-safe shareable summary (markdown + SVG card)
npx @wartzar-bee/tokenscope --share-svg   # just the SVG "cost report card"
npx @wartzar-bee/tokenscope scan          # static token footprint of a source dir (the engine behind ci-guardrail)
npx @wartzar-bee/tokenscope scan --diff ../base   # cost delta of the current dir vs a base dir — catch a regression before you push
npx @wartzar-bee/tokenscope scan --max-total 50000            # exit 1 if the footprint exceeds a budget — a local cost gate
npx @wartzar-bee/tokenscope scan --diff ../base --max-delta 2000   # exit 1 if the diff adds more than N tokens

Lê ~/.claude/projects/**/*.jsonl. Somente leitura, local, sem rede, sem telemetria — abra o código-fonte; nada sai da sua máquina.

Portão de custo local (pré-push / pré-commit)

--max-total N / --max-delta N fazem scan sair com código 1 quando a pegada de tokens (ou o delta de um diff) estoura um orçamento — a mesma verificação que o ci-guardrail executa no CI, mas localmente, antes de você fazer push. Vincule o orçamento absoluto a um hook do git para que um prompt/config descontrolado nunca saia da sua máquina:

# .git/hooks/pre-push  (chmod +x)
npx -y @wartzar-bee/tokenscope scan --dir prompts --max-total 50000 \
  || { echo "prompt token footprint over budget — trim before pushing"; exit 1; }

Dentro do orçamento, imprime o relatório e sai com código 0; acima do orçamento, imprime uma linha BLOCKED: e sai com código 1. Sem a flag --max-*, scan apenas reporta (código 0), então é opt-in. --max-delta controla o delta entre dois diretórios no disco (scan --diff <baseDir> --max-delta N) — aponte-o para uma árvore base com checkout quando quiser um portão de regressão em vez de um limite absoluto.

Usando o framework pre-commit? Adicione tokenscope ao seu .pre-commit-config.yaml — sem scripts de hook do git:

repos:
  - repo: https://github.com/wartzar-bee/tokenscope
    rev: v0.2.6
    hooks:
      - id: tokenscope
        args: ["--dir", "prompts", "--max-total", "50000"]   # optional — omit to just report

language: node, zero dependências. Sem args, imprime a pegada (código 0); adicione --max-total N (ou --diff <baseDir> --max-delta N) para falhar o commit acima do orçamento.

Compartilhe sua conta (seguro para privacidade)

--share emite um resumo compacto construído apenas com números agregados — sem caminhos de arquivo, sem conteúdo de prompt/resposta — então é seguro colar em público:

Markdown para Reddit / Discord / uma issue do GitHub (total, a divisão saída/leitura de cache/escrita de cache/entrada nova com %, contexto pico/médio, e a manchete "X% do gasto foi contexto reenviado").
Um SVG "cartão de relatório de custo" autocontido (--share-svg) — sem dependências binárias; renderiza inline no GitHub e é trivialmente compartilhável.
Como você se compara — ambas as formas agora respondem "minha sessão é incomum?" contra um conjunto de referência offline incluído de sessões reais (ex.: "mais eficiente em cache do que ~80% das sessões medidas; sessão mediana reenvia 24%"). É uma régua de referência, não um censo — distribuição honesta completa em tokenscope.pages.dev/benchmark.

Prefere não tocar em uma flag de terminal? A mesma renderização roda inteiramente no seu navegador na superfície web em web/: cole sua saída --json e ele desenha o relatório completo + o cartão SVG localmente — nada é enviado.

Use de um agente de IA (servidor MCP)

Há um servidor MCP que expõe o mesmo motor a agentes de IA / clientes MCP (Claude Desktop, Claude Code, etc.) como ferramentas: analyze_claude_cost, get_cost_benchmark e tokenscope_share_summary. Adicione-o à sua configuração MCP:

{ "mcpServers": { "tokenscope": { "command": "npx", "args": ["-y", "@wartzar-bee/tokenscope-mcp"] } } }

Então pergunte ao seu agente "use tokenscope para analisar minha última sessão do Claude Code." É o mesmo motor local, somente leitura — veja mcp/README.md.

Preços

Usa preços padrão documentados (multiplicadores de cache Anthropic: escrita 1,25×/2×, leitura 0,1× da entrada). Verifique e substitua para seu modelo/tier exato via ./.tokenscope.json:

{ "pricing": { "claude-opus-4": { "in": 15, "out": 75 } } }

Modelos desconhecidos são sinalizados (nunca contados silenciosamente como $0). As contagens de tokens são lidas diretamente dos logs; custo = essas contagens × os preços mostrados.

Parte do kit de custo wartzar-bee

tokenscope é o motor de medição por trás de uma ferramenta irmã, e um de três projetos de custo de código aberto:

ci-guardrail — uma GitHub Action que executa tokenscope no CI para prever o delta de custo de tokens de um pull request e comentar nos arquivos responsáveis (somente relatório, ou falhar o build acima de um limite): uses: wartzar-bee/ci-guardrail@v1.
enclave — o runtime e sandbox self-hosted, com foco em segurança, no qual a frota de agentes wartzar-bee roda (Apache-2.0).

Se você acha tokenscope útil, ci-guardrail é a maneira zero-config de executá-lo em todo PR.

Por que isso existe — leitura adicional

tokenscope surgiu de rodar agentes autônomos e observar a conta. Os artigos por trás disso:

Coloquei um agente em um timer — durante a noite ele queimou 136M de tokens fazendo quase nada — o postmortem de custo descontrolado que começou isso.
Para onde sua conta do Claude Code realmente vai — medi 66 das minhas próprias sessões — a análise empírica que tokenscope automatiza.
A fórmula de custo do Claude Code: por que a mesma sessão pode custar 10× mais amanhã — a mecânica de custo que tokenscope revela.
Série de auditoria de custo — auditorias reproduzíveis de custo de tokens de frameworks de agentes populares (LangChain, AutoGen, CrewAI, …).
Capture regressões de custo de tokens no CI antes que cheguem à produção — tokenscope como um portão de custo de GitHub Action nos seus PRs.

Status / roadmap

v0.1: custo de sessão do Claude Code + atribuição de contexto + insights. 20/20 testes unitários na matemática de custo (npm test).
Próximo (baseado em evidências): atribuição de tokens por ferramenta/arquivo; alertas diários/orçamentários; um medidor ao vivo --watch; suporte a logs OpenAI/Codex.

MIT. Não afiliado à Anthropic.