Con la popularización de Claude Code —y, especialmente, con planes de suscripción que invitan a usarlo sin mirar atrás— ha empezado a aparecer un nuevo tipo de ansiedad: no la de “¿puedo?”, sino la de “¿cuánto estoy consumiendo realmente?”. En equipos de desarrollo y en entornos de administración de sistemas, donde el control de costes y la trazabilidad importan tanto como la productividad, esa pregunta es más que curiosidad: es una forma de gobernanza.
En ese contexto se está abriendo hueco ccusage (claude-code-usage), una herramienta en formato CLI que analiza el uso de Claude Code a partir de ficheros JSONL locales y lo convierte en informes claros por día, semana, mes, sesión o “bloques” de facturación. La propuesta es directa: no toca tus proyectos, no necesita integrar nada en la nube, y se limita a leer datos que ya existen en tu máquina para ayudarte a entender patrones de consumo y costes estimados.
Por qué ha empezado a importar tanto “medir” el asistente
La adopción de herramientas de Inteligencia Artificial en programación tiene un efecto colateral: la conversación se convierte en una métrica. Cada refactor, cada prompt largo, cada iteración de pruebas y cada sesión maratoniana de depuración deja un rastro de tokens. Y cuando el uso se vuelve intensivo, el coste (o el valor) deja de ser una intuición.
ccusage parte de una realidad práctica: Claude Code genera ficheros de uso en local y el usuario quiere responder preguntas muy concretas: qué días ha usado más, qué sesiones “queman” más tokens, qué modelos se han empleado y qué coste aproximado habría supuesto con tarifas por uso. La documentación del proyecto lo plantea justo así: dar visibilidad a patrones y “coste estimado” a partir del rastro local, con salida en tablas o en JSON para análisis posterior.
Qué ofrece ccusage (y por qué encaja en equipos técnicos)
Más allá del nombre, lo relevante es el enfoque: ccusage se comporta como un cuadro de mando minimalista, pensado para terminal y para automatización.
Entre sus funciones destacadas:
- Informes diarios, semanales y mensuales, con agregación por fecha y desglose.
- Informes por sesión, útiles para ver qué conversaciones han sido más costosas o intensas.
- Bloques de 5 horas, orientados a seguir ventanas de facturación y monitorización activa.
- Seguimiento de modelos, para distinguir el uso entre familias (por ejemplo, Opus o Sonnet).
- Cálculo de coste estimado, con desglose y soporte para tokens de caché (creación y lectura).
- Modo offline, pensado para entornos sin conectividad o con restricciones.
- Integración MCP, al incluir un servidor de Model Context Protocol para integrarlo como herramienta en otros flujos.
Hay un detalle que, en la práctica, es una declaración de intenciones: el proyecto insiste en un bundle pequeño y en la posibilidad de ejecutarlo “al vuelo” (por ejemplo, con bunx) para usarlo sin fricción. En equipos donde todo acaba en un script o en un job, esto no es postureo: es ergonomía.
Dónde mira: el cambio de ruta que puede despistar
Uno de los puntos más útiles de la guía es que aclara algo que, si no, genera confusión: la ubicación de los datos locales cambió en versiones recientes de Claude Code. Según la documentación, la ruta “nueva” pasa por ~/.config/claude/projects/ (Claude Code v1.0.30 o superior), mientras que la “legacy” era ~/.claude/projects/. La herramienta detecta y agrega datos de ambas para mantener compatibilidad.
Para un perfil sysadmin, esto tiene dos implicaciones obvias:
- si se “pierden” informes, muchas veces no es que falten datos: están en otra ruta;
- si se quiere centralizar telemetría interna (por ejemplo, en un portátil corporativo), el punto de recolección está bien delimitado.
Privacidad: la parte aburrida que aquí es decisiva
En un mercado lleno de integraciones que piden permisos de todo tipo, ccusage juega otra carta: análisis 100% local, sin transmisión de datos, y con comportamiento solo lectura. En otras palabras, convierte el consumo en métricas sin abrir un nuevo frente de riesgo.
Un ejemplo rápido de uso en terminal
Sin convertir esto en un tutorial, el tipo de uso que busca la herramienta es el de “dame un resumen ahora mismo”. En esa línea, ejecutar un informe suele ser tan simple como:
bunx ccusage daily
bunx ccusage weekly
bunx ccusage session
La salida está pensada para verse bien en terminal, pero también puede exportarse en JSON cuando el objetivo es integrarlo en pipelines internos o en reporting.
Preguntas frecuentes
¿Qué es ccusage y para qué sirve en Claude Code?
Es una herramienta CLI que analiza el uso de Claude Code leyendo ficheros JSONL locales y genera informes por día, semana, mes, sesión y bloques, con estimaciones de coste y desglose por modelos.
¿Dónde guarda Claude Code los datos que analiza ccusage?
La guía indica dos ubicaciones: ~/.config/claude/projects/ en Claude Code v1.0.30+ y la ruta anterior ~/.claude/projects/. ccusage puede detectar y agregar ambas.
¿ccusage envía mis datos fuera del equipo?
Según la documentación, no: el análisis ocurre en local, no hay transmisión de datos y la herramienta se limita a leer los archivos sin modificarlos.
¿Qué aporta el informe por “bloques de 5 horas”?
Permite agrupar y seguir el consumo dentro de ventanas de 5 horas asociadas al seguimiento de uso y monitorización, útil para entender picos y ritmos de consumo durante sesiones intensivas.
vía: ccusage
