¿Qué es ccusage?
ccusage lee los registros de uso que Claude Code y otras CLI de agentes guardan en tu máquina e informa de tokens y coste estimado por día, semana, mes o sesión. Para Claude Code también muestra los bloques de facturación de 5 horas con una vista en directo y ofrece una statusline compacta (en beta) para la barra de estado de Claude Code.
Se ejecuta con `npx ccusage@latest` (o bunx, pnpm dlx, Nix) y no necesita cuenta ni clave de API. El README enumera 18 fuentes, entre ellas Claude Code, Codex, OpenCode, Amp, Goose, Kilo, Gemini CLI y GitHub Copilot CLI. Los precios salen de LiteLLM, models.dev y tablas históricas integradas, guardados en caché local, con un modo `--offline`.
¿Merece la pena ccusage?
ccusage se ha convertido en el contador local por defecto para el uso de agentes de programación. Tiene unas 19.100 estrellas en GitHub, npm contó cerca de 871.000 descargas en los 30 días hasta el 18 de octubre de 2026, y publica versiones casi a diario: de la v20.0.34 el 15 de octubre a la v20.0.41 el 22 de octubre. Lo empezó ryoppippi, ahora está bajo una organización ccusage, y el código es Rust, aunque se sigue distribuyendo por npm.
La columna de coste hay que leerla con cuidado. En el modo auto por defecto usa el costUSD que guarda Claude Code cuando existe y, si no, multiplica los tokens por los precios por token publicados. La documentación dice claramente que los costes "pueden no reflejar la facturación real" y que no se incluyen llamadas a herramientas como la búsqueda web. Con una suscripción Pro o Max la cifra no es tu factura; es lo que el mismo trabajo habría costado con tarifas de pago por uso.
El límite menos evidente es el historial. Claude Code guarda las transcripciones locales 30 días por defecto (el ajuste cleanupPeriodDays), y ccusage solo puede contar lo que sigue en disco. Quien quiera la tendencia de un trimestre tiene que subir antes ese ajuste, o exportar instantáneas con `--json` de forma programada.
Según la documentación, los datos de uso nunca salen de la máquina, pero por defecto ccusage sí actualiza su caché de precios por la red; `--offline` lo impide. Los informes separan por modelo los tokens de entrada, de salida, de creación de caché y de lectura de caché, que es el desglose necesario para saber si un cambio en el prompt caching o un plugin de ahorro de tokens ha ayudado de verdad.
Su alcance es una sola máquina. No hay servidor ni vista de equipo documentados, así que un responsable que compare a diez desarrolladores tiene que reunir y sumar diez archivos JSON a mano, y cada uno es tan completo como lo sea la retención de registros de ese portátil.
Dónde se gana su sitio
Un desarrollador que prueba un plugin de ahorro de tokens como RTK
Demostrar si de verdad reduce el uso
Ejecuta `ccusage daily --json` durante una semana antes y otra después de instalarlo y compara los tokens de entrada y de lectura de caché por modelo. Lleva minutos y no cuesta nada; la comparación solo es justa si las cargas de trabajo de las dos semanas lo son.
Una responsable de ingeniería que paga puestos de Claude Max
Decidir si pasar al equipo a facturación por API saldría más barato
Cada desarrollador ejecuta `ccusage monthly --json` y comparte el archivo; los totales muestran lo que costaría el mismo uso con tarifas de API. Como no hay vista compartida, reunir y sumar los archivos es manual.
Un desarrollador autónomo que factura a varios clientes
Asignar el gasto en agentes a cada proyecto de cliente
`ccusage claude daily --instances --project <name>` agrupa el uso de Claude Code por proyecto; la cifra equivalente a la API es una partida defendible si el contrato factura las herramientas a coste.
Antes de decidirte
- Puesta en marcha
- `npx ccusage@latest` muestra un informe diario en segundos; bunx guarda el paquete en caché para que las siguientes ejecuciones sean más rápidas. Añade `ccusage statusline` al hook de la línea de estado de Claude Code para ver una cifra en directo.
- Integraciones
- Lee registros locales de 18 CLI de agentes, entre ellas Claude Code (~/.claude y ~/.config/claude/projects), Codex, OpenCode, Gemini CLI y Copilot CLI; genera tablas o JSON; los precios personalizados van en ccusage.json.
- Datos y privacidad
- El análisis es local y los datos de uso no se suben, según la documentación; los datos de precios se descargan y guardan en caché salvo que uses --offline. Licencia MIT, así que el uso comercial no tiene restricciones.
- Coste a escala
- Gratis, sin edición de pago; se financia con patrocinios. El único coste es la costumbre de ejecutarlo en cada máquina que quieras contar.
- Límites
- Las cifras en dólares son estimaciones que excluyen la búsqueda web; Claude Code borra las transcripciones a los 30 días salvo que se suba cleanupPeriodDays; no hay agregación por equipo. Solo 4 incidencias abiertas en la última revisión.
Lo bueno
- Informes totalmente locales y sin cuenta
- 18 CLI de agentes en un solo informe
- Separa por modelo los tokens de creación y de lectura de caché
- Vista de bloques de 5 horas, statusline y salida --json
Lo malo
- Los costes son estimaciones equivalentes a la API y excluyen la búsqueda web
- El historial se limita a lo que el agente guarda en disco (30 días para Claude Code por defecto)
- Sin modo de equipo ni de servidor
Ideal para
Cualquiera que quiera seguir o comparar el uso de tokens entre sesiones de agentes.
Alternativas a ccusage
ccusage: preguntas frecuentes
- ¿Merece la pena ccusage?
- ccusage es el contador que todo usuario intensivo de agentes debería usar, siempre que lea su columna en dólares como lo que el trabajo habría costado en la API, no como lo que ha pagado. Le damos un 4.4 sobre 5.
- ¿Cuánto cuesta ccusage?
- Gratuito y de código abierto (MIT).
- ¿Qué inconvenientes tiene ccusage?
- Los costes son estimaciones equivalentes a la API y excluyen la búsqueda web; el historial se limita a lo que el agente guarda en disco (30 días para Claude Code por defecto); sin modo de equipo ni de servidor.
- ¿Para quién es ccusage?
- Cualquiera que quiera seguir o comparar el uso de tokens entre sesiones de agentes.
- ¿Cuánto cuesta ccusage para un equipo o en producción?
- Gratis, sin edición de pago; se financia con patrocinios. El único coste es la costumbre de ejecutarlo en cada máquina que quieras contar.
- ¿Es ccusage seguro para los datos de la empresa?
- El análisis es local y los datos de uso no se suben, según la documentación; los datos de precios se descargan y guardan en caché salvo que uses --offline. Licencia MIT, así que el uso comercial no tiene restricciones.
- ¿Cuáles son las mejores alternativas a ccusage?
- Las alternativas más cercanas que hemos analizado son rtk (Rust Token Killer), Claude Code Router y mindwalk.
Respuestas comprobadas el 23 oct 2026.