ccusage - Herramienta de análisis del uso de Claude Code

Resumen del proyecto

ccusage es una herramienta CLI para analizar los datos de uso de Claude Code en archivos JSONL locales. Este proyecto fue desarrollado por @ryoppippi, inspirado en un artículo sobre el seguimiento de los costos de uso de Claude Code.

Características principales

📊 Múltiples tipos de informes

• Informe diario: Resume el uso de tokens y los costos por fecha
• Informe mensual: Resume el uso de tokens y los costos por mes
• Informe por sesión: Muestra el uso agrupado por sesión de conversación
• Informe por bloques de 5 horas: Informes basados en ventanas de facturación de 5 horas
• Línea de estado: Línea de estado compacta para hooks (versión Beta)

🎯 Potentes funciones de filtrado y análisis

• Filtrado por fecha: Filtra informes por rango de fechas usando --since y --until
• Análisis por proyecto: Agrupa por proyecto/instancia, soporta filtrado por proyectos específicos
• Desglose de costos por modelo: Desglose de costos para cada modelo
• Zona horaria y localización: Soporte para la zona horaria UTC y formato de localización japonés

🎨 Salida y visualización atractivas

• Visualización en formato de tabla a color con diseño responsivo automático
• Tablas inteligentes: Modo compacto automático para terminales estrechas (<100 caracteres), mostrando columnas esenciales
• Modo compacto: Usa el flag --compact para forzar un diseño de tabla compacto, ideal para capturas de pantalla y compartir
• Visualización mejorada del modelo: Los nombres de los modelos se muestran como una lista con viñetas para mejorar la legibilidad

💰 Funciones de seguimiento de costos

• Muestra los costos diarios/mensuales/por sesión en USD
• Soporte para tokens de caché: Rastrea y muestra por separado los tokens de creación de caché y lectura de caché
• Modo sin conexión: Usa --offline para utilizar datos de precios precargados sin conexión a la red (solo modelos Claude)

⚡ Monitoreo en tiempo real

• Panel de uso en tiempo real
• Monitoreo en tiempo real: ccusage blocks --live

Instalación y uso

Inicio rápido (sin instalación)

Dado que ccusage tiene un tamaño de paquete extremadamente pequeño, se puede ejecutar directamente sin necesidad de instalación:

# Usando bunx (recomendado, más rápido)
bunx ccusage

# Usando npx
npx ccusage@latest

# Usando deno (con flags de seguridad)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

Instalación global

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

# Instalación global con bun
bun install -g ccusage

# Luego ejecutar
ccusage

Entorno de desarrollo

# Clonar el repositorio
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Instalar dependencias
bun install

# Ejecutar la herramienta
bun run report [subcommand] [options]

Uso básico

Informe diario

# Mostrar todo el uso diario
ccusage daily

# Filtrar por rango de fechas
ccusage daily --since 20250525 --until 20250530

# Usar un directorio de datos de Claude personalizado
ccusage daily --path /custom/path/to/.claude

# Salida en formato JSON
ccusage daily --json

# Desglose de costos por modelo
ccusage daily --breakdown

# Usar la zona horaria UTC
ccusage daily --timezone UTC

# Usar localización japonesa
ccusage daily --locale ja-JP

Análisis por proyecto

# Agrupar por proyecto/instancia
ccusage daily --instances

# Filtrar por un proyecto específico
ccusage daily --project myproject

# Uso combinado
ccusage daily --instances --project myproject --json

Informe por sesión

# Mostrar todas las sesiones
ccusage session

# Filtrar sesiones por fecha de última actividad
ccusage session --since 20250525

# Combinar filtros
ccusage session --since 20250525 --until 20250530 --path /custom/path

# Salida en formato JSON
ccusage session --json

Monitoreo en tiempo real

# Panel de uso en tiempo real
ccusage blocks --live

# Ventana de facturación de 5 horas
ccusage blocks

# Línea de estado (Beta)
ccusage statusline

Modo compacto

# Forzar modo de tabla compacta
ccusage --compact

# Informe mensual compacto
ccusage monthly --compact

Opciones de comando

Todos los comandos soportan las siguientes opciones:

• -s, --since <date>: Filtrar desde la fecha (formato YYYYMMDD)
• -u, --until <date>: Filtrar hasta la fecha (formato YYYYMMDD)
• -p, --path <path>: Ruta personalizada para el directorio de datos de Claude (por defecto: ~/.claude)
• -j, --json: Salida de resultados en formato JSON en lugar de tabla
• -h, --help: Muestra información de ayuda
• -v, --version: Muestra la versión

Ejemplos de salida

Salida del informe diario

╭──────────────────────────────────────────╮
│                                          │
│ Informe de uso de tokens de Claude Code - Diario │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ Date             │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ Total            │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

Salida del informe por sesión

╭───────────────────────────────────────────────╮
│                                               │
│ Informe de uso de tokens de Claude Code - Por Sesión │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ Project / Session            │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │ Last Activity │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ Total                        │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

Arquitectura técnica

Requisitos de dependencia

• Entorno de ejecución Bun
• Archivos de historial de uso de Claude Code (~/.claude/projects/**/*.jsonl)

Estructura del proyecto

ccusage/
├── commands/
│   ├── daily.ts        # Comando de informe diario
│   └── session.ts      # Comando de informe por sesión
├── data-loader.ts      # Lógica de carga de datos JSONL
├── index.ts           # Punto de entrada CLI
├── logger.ts          # Configuración de registro
├── utils.ts           # Utilidades compartidas
└── package.json

Desarrollo y pruebas

# Ejecutar pruebas
bun test

# Verificación de tipos
bun run typecheck

# Linting de código
bun run lint

# Formatear código
bun run format

Funciones de integración

🔌 Integración MCP

Servidor de Protocolo de Contexto de Modelo (MCP) incorporado para la integración con otras herramientas

Resumen

ccusage es una herramienta CLI potente y fácil de usar, diseñada específicamente para usuarios de Claude Code, para analizar y rastrear el uso de tokens y los costos asociados. Su diseño ligero, su rico conjunto de funciones y su atractiva salida la convierten en una opción ideal para los desarrolladores que buscan optimizar el uso de Claude Code y gestionar los costos.