CodeBurn y el problema que no sabía que tenía: cuántos tokens gasto por tarea real

En 2005, cuando el cyber café se llenaba un viernes a la noche, yo tenía una métrica muy clara: minutos hasta que volvía la conexión. Cada minuto era plata que se perdía — no la mía, del dueño, pero el peso lo sentía yo. Aprendí muy rápido a distinguir qué problemas valía la pena atacar con ensayo y error y cuáles necesitaban diagnóstico preciso primero. Gastar cinco minutos probando cables antes de mirar los logs era un lujo que no podía darme.

Hoy tengo una métrica nueva que me genera la misma tensión: tokens por tarea real en Claude Code. Y la aprendí igual — a los golpes, cuando CodeBurn apareció en Hacker News esta mañana y me obligó a sentarme a calcular mis propios números por primera vez.

Claude Code token usage análisis: lo que CodeBurn hace que el dashboard no hace

CodeBurn es una herramienta CLI que parsea los logs de Claude Code y te da un breakdown por sesión, por tarea, por tipo de operación. No es magia — Claude Code ya loguea todo localmente en ~/.claude/projects/. Lo que CodeBurn hace es convertir ese JSON en algo legible.

Instalación:

# Instalación global con npm
npm install -g codeburn

# O si preferís no instalarlo globalmente
npx codeburn analyze

El comando que más me importó:

# Analizar el proyecto actual con breakdown por sesión
codeburn analyze --project . --breakdown session

# Ver el costo estimado en USD (usa pricing de Anthropic)
codeburn analyze --project . --cost

# El que cambió cómo pienso: tokens por tarea completada
codeburn analyze --project . --per-task

Ese --per-task requiere que tus commits tengan mensajes descriptivos o que hayas usado el feature de tareas de Claude Code. Si laburás con commits atómicos (debería ser obligatorio), funciona bastante bien.

El dashboard de Anthropic te muestra tokens totales por período. Útil para billing, inútil para diagnóstico. La diferencia es la misma que entre ver tu factura de luz y tener un medidor por habitación.

Los números que me incomodaron

Tomé tres tipos de tareas reales de la última semana y medí:

Tarea 1: Agregar autenticación JWT a un endpoint existente

Tokens input:  ~12,400
Tokens output: ~3,200  
Total:         ~15,600
Tiempo:        ~22 minutos
Commits:       3

Desglose aproximado:
- Lectura de contexto inicial:     4,100 tokens
- Generación de código:            2,800 tokens
- Corrección de tipos TypeScript:  5,200 tokens  ← acá está el problema
- Tests:                           3,500 tokens

Ese bloque de corrección de tipos fue tres idas y vueltas donde le di tipos incorrectos en el contexto inicial. No fue un problema del agente — fue mío. No le di la interfaz existente, asumí que la iba a inferir.

Tarea 2: Migración de schema en PostgreSQL con Railway

Tokens input:  ~31,800
Tokens output: ~8,900
Total:         ~40,700
Tiempo:        ~45 minutos
Commits:       2

Desglose aproximado:
- Contexto del schema actual:      8,200 tokens
- Plan de migración:               3,100 tokens  
- Debugging de foreign keys:      19,400 tokens  ← esto es el problema
- Validación final:                1,000 tokens

Casi la mitad de los tokens de esa sesión fueron debuggear un problema de orden de operaciones en las foreign keys. El agente propuso cuatro soluciones distintas, tres fallaron, la cuarta funcionó. ¿Era evitable? Probablemente sí — si yo hubiera descripto el orden de dependencias en el prompt inicial en vez de dejárselo inferir.

Tarea 3: Componente React con formulario validado

Tokens input:  ~8,900
Tokens output: ~4,100
Total:         ~13,000
Tiempo:        ~18 minutos
Commits:       4

Desglose aproximado:
- Contexto y specs:                2,200 tokens
- Generación del componente:       3,800 tokens
- Ajustes de UX menores:           4,100 tokens
- Refinamiento final:              2,900 tokens

Esta fue la más limpia. Sin iteraciones largas de debug. Los ajustes fueron funcionales, no correcciones de errores.

El patrón que emergió: las iteraciones de corrección de errores cuestan tres veces más que las de refinamiento funcional. Y la mayoría de mis errores venían del contexto que yo proveía, no del agente.

Ya escribí antes sobre la opacidad del token usage en herramientas IA — pero ahí hablaba de herramientas que no te decían qué estaban gastando. Esto es diferente: Claude Code sí lo loguea, simplemente yo no lo estaba mirando.

Los errores de diseño que los tokens revelan

Acá es donde esto deja de ser una nota de costos y se convierte en algo más interesante.

Cuando medís tokens por tarea y los desglosás, estás midiendo indirectamente la calidad de tu especificación inicial. Un ratio alto de tokens de corrección vs. tokens de generación es una señal de que algo en tu flujo de trabajo está roto.

Los patrones que encontré en mis propias sesiones:

Patrón 1: Contexto insuficiente al inicio

El agente necesita leer archivos adicionales que yo debería haberle dado. Eso son miles de tokens de lectura que se podrían evitar con un CLAUDE.md bien mantenido o con @file explícitos en el prompt inicial.

# En vez de: "arreglá el bug en el componente de auth"
# Hacé esto:

# Primero revisá qué archivos son relevantes
cat CLAUDE.md  # si tenés uno

# Después incluí el contexto explícitamente
# "arreglá el bug en @src/auth/AuthProvider.tsx
#  considerando los tipos en @types/auth.d.ts
#  y los tests existentes en @__tests__/auth.test.ts"

Patrón 2: Tarea mal definida que genera iteraciones

"Mejorá el rendimiento del componente" genera cinco preguntas de clarificación o cinco intentos distintos. "Eliminá re-renders innecesarios en UserList usando React.memo donde el prop es un objeto estable" genera una respuesta.

Patrón 3: El loop de debug sintomático

Cuando el agente entra en un loop de más de dos correcciones del mismo tipo de error, generalmente hay algo que él no puede saber porque yo no se lo dije. La señal no es "el agente es malo" — la señal es "hay contexto faltante".

Esto conecta con algo que mencioné en el post sobre cosas que sobreingeniás en tu agente de IA — a veces el problema no es la herramienta, es cómo la usás.

Un script simple para empezar a medir sin CodeBurn

Si no querés instalar otra herramienta todavía, los logs están en ~/.claude/projects/[hash-del-proyecto]/. Son JSONs. Podés parsearlos vos:

#!/bin/bash
# Script básico para ver tokens de la última sesión
# Guardalo como ~/bin/claude-tokens

PROJECT_DIR="$HOME/.claude/projects"

# Encontrar el proyecto más reciente
LATEST=$(ls -t "$PROJECT_DIR" | head -1)

if [ -z "$LATEST" ]; then
  echo "No se encontraron proyectos de Claude Code"
  exit 1
fi

echo "Proyecto: $LATEST"
echo "---"

# Parsear el último archivo de sesión con jq
LATEST_SESSION=$(ls -t "$PROJECT_DIR/$LATEST"/*.jsonl 2>/dev/null | head -1)

if [ -z "$LATEST_SESSION" ]; then
  echo "No se encontraron sesiones"
  exit 1
fi

# Sumar tokens de input y output
jq -s '
  map(select(.type == "assistant" and .usage != null)) |
  {
    input_tokens: (map(.usage.input_tokens) | add),
    output_tokens: (map(.usage.output_tokens) | add),
    total_turnos: length
  }
' "$LATEST_SESSION"

Esto es básico — CodeBurn hace mucho más. Pero te da los números en 30 segundos sin instalar nada extra.

Nota: la estructura exacta de los logs puede variar según la versión de Claude Code. Si el script no funciona, revisá la estructura con cat [archivo].jsonl | head -5 | jq '.'.

Errores comunes cuando empezás a medir esto

Error 1: Optimizar para tokens en vez de para claridad

Vi esto en Twitter apenas salió CodeBurn — gente que empieza a hacer prompts ultracortos para gastar menos tokens. Contraproducente. Un prompt de 50 tokens que genera tres iteraciones de corrección es más caro que un prompt de 300 tokens bien especificado. Optimizás el ratio, no el total de input.

Error 2: Interpretar gasto alto como señal de complejidad

A veces sí — una migración compleja va a gastar más. Pero gasto alto en tareas simples es la señal que importa. Si agregar un campo a un formulario te cuesta 20k tokens, hay algo roto en tu flujo.

Error 3: No separar sesiones por tarea

Si abrís una sesión de Claude Code y resolvés cuatro problemas distintos sin cerrarla, los números son inútiles para diagnóstico. Una sesión, una tarea. Esto también mejora la calidad de las respuestas porque el contexto no se contamina.

Error 4: Ignorar el costo de los tool calls

Cada vez que el agente lee un archivo, ejecuta un comando, busca en el codebase — eso son tokens. No son muchos individualmente, pero en sesiones largas se acumulan. Un agente que lee 15 archivos para resolver algo que requería 3 no es eficiente — y eso generalmente es un problema de cómo organizaste tu proyecto o tu CLAUDE.md.

Este tema de visibilidad sobre lo que gastan las herramientas también aparece en mi post sobre seguridad como proof of work — la opacidad no es neutral, tiene consecuencias reales.

FAQ: Claude Code token usage y análisis de costos

¿CodeBurn es oficial de Anthropic?

No. Es una herramienta de terceros que parsea los logs locales que Claude Code genera por defecto. Anthropic no lo mantiene. Los logs sí son oficiales y están en tu máquina — CodeBurn solo los hace legibles.

¿Cuánto cuesta Claude Code en tokens por sesión típica de desarrollo?

Depende enormemente del tipo de tarea y de qué tan bien especificado esté el contexto. En mi experiencia, tareas simples (un componente, un endpoint) están entre 10k-20k tokens totales. Tareas complejas con migraciones o refactors grandes pueden ir de 40k a 100k+. El número por sí solo no dice nada — lo que importa es el ratio de tokens de corrección vs. generación.

¿Los logs de Claude Code contienen información sensible?

Sí, potencialmente mucho. Los logs incluyen el código que mostraste al agente, los prompts completos, las respuestas. Si trabajás con código propietario o datos sensibles, es importante saber que todo eso queda en ~/.claude/. Ya escribí sobre los riesgos legales de qué queda registrado en conversaciones con IA — aplica acá también.

¿Qué es un buen ratio de tokens de corrección vs. generación?

No tengo un benchmark oficial, pero en mi experiencia: si más del 40% de tus tokens van a corrección de errores (no a refinamiento funcional), hay algo mejorable en cómo contextualizás las tareas. El refinamiento funcional es sano — "hacé esto más accesible", "agregá manejo de errores" — eso es iteración normal. Las correcciones de tipos, de interfaces mal inferidas, de dependencias que el agente no conocía — esas son las que se pueden prevenir.

¿Vale la pena usar Claude Code si las tareas complejas cuestan 40k+ tokens?

Dependé del valor generado, no del costo absoluto. Una migración de schema que me llevaría 3 horas y que el agente resuelve en 45 minutos con 40k tokens tiene un ROI obvio. Lo que no tiene ROI es usar el agente para tareas donde el overhead de contextualizarlo supera el tiempo que ahorrás. Para cosas de 5 minutos, a veces es más rápido escribirlo vos.

¿Cómo se integra esto con el plan Max de Claude Code?

Si estás en el plan con límite de uso (no por tokens sino por tiempo o requests), la métrica relevante cambia. Pero el análisis cualitativo sigue siendo útil: si estás gastando la mitad de tus requests del día en loops de corrección evitables, igual estás dejando plata sobre la mesa. El recurso escaso cambia, el principio no.

El insight real: los tokens son un proxy de claridad

Me llevó un par de horas con CodeBurn darme cuenta de que no estaba mirando un problema de costos. Estaba mirando un espejo de mi propio proceso de pensamiento.

Cuando le doy contexto incompleto al agente, los tokens de corrección disparan. Cuando la tarea está mal definida, entro en loops. Cuando el codebase no tiene un CLAUDE.md actualizado, el agente lee de más para inferir lo que yo debería haberle dicho.

Nada de eso es nuevo como principio — es lo mismo que pasa cuando le delegás trabajo a una persona sin darle suficiente información. La diferencia es que con una persona el costo es invisible y diferido. Con Claude Code, CodeBurn te lo pone en números en la cara.

No empecé a usar Claude Code pensando en los costos. Empecé porque acelera mi flujo de trabajo de manera genuina. Pero ahora que puedo medir, los tokens se convirtieron en la métrica que me dice cuándo mi especificación inicial fue buena y cuándo fui flojo.

Es la misma lógica del cyber café: no medía el tiempo para optimizar mi sueldo por hora. Lo medía porque era la señal más honesta de si había entendido el problema antes de empezar a moverme.

Si estás usando Claude Code regularmente, instalá CodeBurn o corré el script simple. No para recortar costos — para ver qué tipo de developer sos cuando le delegás trabajo a una máquina.

Los números no mienten, aunque a veces incómoden.

---

Este artículo fue publicado originalmente en juanchi.dev