Tokenscope

Servidor MCP que permite a los agentes de IA analizar el costo de sesión y la atribución de contexto de Claude Code: uso de tokens, relecturas en caché y escrituras en caché. Local, de solo lectura.

GitHub

Prueba este MCPPatrocinado

Documentación

tokenscope ⏣

Mira cuánto costó realmente tu sesión de codificación con IA — y qué está consumiendo tu contexto. Una CLI local de solo lectura que analiza los registros de sesión de Claude Code y muestra a dónde va el dinero: salida del modelo vs. contexto que se re-envía en cada turno (el 60%+ oculto de la mayoría de las facturas).

$ 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.

(Una sesión real, con precios predeterminados de Opus. Tus números diferirán — los precios son sobreescribibles.)

Por qué

La codificación agéntica (Claude Code, etc.) produce facturas sorpresa, y la causa es mundana: a medida que una sesión crece, todo el contexto se re-envía en cada turno, por lo que el costo se dispara incluso cuando el modelo escribe poco. Los paneles existentes muestran totales; tokenscope muestra la atribución — salida vs. lectura de caché vs. escritura de caché vs. entrada nueva, la curva de crecimiento del contexto por turno, costo por modelo, gasto de subagentes, y qué herramientas llenan tu contexto — con ideas concretas de "recorta esto".

Pruébalo en 10 segundos (no se necesitan registros de Claude Code)

npx @wartzar-bee/tokenscope --demo

Se ejecuta en una sesión de muestra incluida para que veas el informe completo antes de apuntarlo a tus propios registros — sin configuración, nada que ajustar. (La muestra es sintética, para demostración.)

Instalación / ejecución

Sin instalación — se ejecuta vía 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

Lee ~/.claude/projects/**/*.jsonl. Solo lectura, local, sin red, sin telemetría — abre el código fuente; nada sale de tu máquina.

Puerta de costo local (pre-push / pre-commit)

--max-total N / --max-delta N hacen que scan salga con código 1 cuando la huella de tokens (o el delta de un diff) excede un presupuesto — la misma verificación que ci-guardrail ejecuta en CI, pero localmente, antes de que hagas push. Conecta el presupuesto absoluto a un gancho de git para que un prompt/config descontrolado nunca salga de tu 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; }

Si está dentro del presupuesto, imprime el informe y sale con 0; si lo excede, imprime una línea BLOCKED: y sale con 1. Sin una bandera --max-*, scan solo informa (salida 0), por lo que es opcional. --max-delta controla el delta entre dos directorios en disco (scan --diff <baseDir> --max-delta N) — apúntalo a un árbol base verificado cuando quieras una puerta de regresión en lugar de un tope absoluto.

¿Usas el framework pre-commit? Añade tokenscope a tu .pre-commit-config.yaml — sin scripting de ganchos de 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, cero dependencias. Sin args imprime la huella (salida 0); añade --max-total N (o --diff <baseDir> --max-delta N) para fallar el commit si excede el presupuesto.

Comparte tu factura (seguro para la privacidad)

--share emite un resumen compacto construido solo con números agregados — sin rutas de archivo, sin contenido de prompts/respuestas — por lo que es seguro pegarlo en público:

Markdown para Reddit / Discord / un issue de GitHub (total, el desglose de salida/lectura de caché/escritura de caché/entrada nueva con %, contexto pico/promedio, y el titular "X% del gasto fue contexto re-enviado").
Una "tarjeta de informe de costos" SVG autocontenida (--share-svg) — sin dependencias binarias; se renderiza en línea en GitHub y es trivialmente compartible.
Cómo te comparas — ambas formas ahora responden "¿es inusual mi sesión?" contra un conjunto de referencia offline incluido de sesiones reales (p. ej. "más eficiente en caché que ~80% de las sesiones medidas; la sesión mediana re-envía 24%"). Es una vara de medir de referencia, no un censo — distribución honesta completa en tokenscope.pages.dev/benchmark.

¿Prefieres no tocar una bandera de terminal? El mismo render se ejecuta enteramente en tu navegador en la superficie web de web/: pega tu salida --json y dibuja el informe completo + la tarjeta SVG localmente — nada se sube.

Úsalo desde un agente de IA (servidor MCP)

Hay un servidor MCP que expone el mismo motor a agentes de IA / clientes MCP (Claude Desktop, Claude Code, etc.) como herramientas: analyze_claude_cost, get_cost_benchmark, y tokenscope_share_summary. Añádelo a tu configuración MCP:

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

Luego pídele a tu agente "usa tokenscope para analizar mi última sesión de Claude Code." Es el mismo motor local de solo lectura — ver mcp/README.md.

Precios

Usa precios predeterminados documentados (multiplicadores de caché de Anthropic: escritura 1.25×/2×, lectura 0.1× de entrada). Verifica y sobreescribe para tu modelo/nivel exacto vía ./.tokenscope.json:

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

Los modelos desconocidos se marcan (nunca se cuentan silenciosamente como $0). Los conteos de tokens se leen directamente de los registros; costo = esos conteos × los precios mostrados.

Parte del kit de herramientas de costos wartzar-bee

tokenscope es el motor de medición detrás de una herramienta hermana, y uno de tres proyectos de costos de código abierto:

ci-guardrail — una GitHub Action que ejecuta tokenscope en CI para predecir el delta de costo de tokens de un pull request y comentar sobre los archivos responsables (solo informe, o fallar la compilación más allá de un umbral): uses: wartzar-bee/ci-guardrail@v1.
enclave — el runtime y sandbox autohospedado y centrado en seguridad sobre el que corre la flota de agentes wartzar-bee (Apache-2.0).

Si encuentras útil tokenscope, ci-guardrail es la forma de configuración cero para ejecutarlo en cada PR.

Por qué existe esto — lecturas adicionales

tokenscope surgió de ejecutar agentes autónomos y observar la factura. Los artículos detrás de él:

Puse un agente en un temporizador — durante la noche quemó 136M tokens haciendo casi nada — la autopsia del costo descontrolado que inició esto.
A dónde va realmente tu factura de Claude Code — medí 66 de mis propias sesiones — el desglose empírico que tokenscope automatiza.
La fórmula de costo de Claude Code: por qué la misma sesión puede costar 10× más mañana — la mecánica de costos que tokenscope revela.
Serie de auditoría de costos — auditorías reproducibles de costos de tokens de frameworks de agentes populares (LangChain, AutoGen, CrewAI, …).
Detecta regresiones de costo de tokens en CI antes de que se publiquen — tokenscope como puerta de costo de GitHub Action en tus PRs.

Estado / hoja de ruta

v0.1: costo de sesión de Claude Code + atribución de contexto + insights. 20/20 pruebas unitarias sobre la matemática de costos (npm test).
Siguiente (impulsado por evidencia): atribución de tokens por herramienta/archivo; alertas diarias/presupuesto; un medidor en vivo --watch; soporte de registros de OpenAI/Codex.

MIT. No afiliado con Anthropic.