3 Herramientas Open Source para Monitorear el Uso de Claude Code

Para los Vibe Coders, herramientas como Claude Code de Anthropic se han vuelto indispensables para muchos ingenieros. Desde la generación de código repetitivo hasta la depuración de algoritmos complejos, Claude Code puede aumentar significativamente la productividad. Sin embargo, este poder conlleva la necesidad de supervisión. Un uso sin monitoreo puede llevar a costos inesperados, cuellos de botella en el rendimiento y una comprensión incompleta de cómo estas potentes herramientas están impactando su ciclo de vida de desarrollo.

Un monitoreo efectivo no se trata solo de rastrear gastos; se trata de comprender el valor. ¿Está utilizando los modelos más rentables para sus tareas? ¿Existen patrones en su flujo de trabajo que podrían optimizarse? ¿Cómo se traduce la asistencia de IA en ganancias tangibles de productividad para su equipo? Responder a estas preguntas requiere datos, y ahí es donde entran en juego las herramientas de monitoreo de código abierto.

Aunque Claude Code proporciona cierto nivel de información de uso, ha surgido un ecosistema dedicado de herramientas de código abierto para ofrecer información más profunda y procesable. Estas herramientas satisfacen una variedad de necesidades, desde el desarrollador individual que desea una verificación rápida de su consumo diario de tokens hasta el equipo empresarial que busca construir una plataforma de observabilidad integral en torno a su uso de IA.

En este artículo, profundizaremos en tres herramientas de código abierto distintas que le ayudarán a monitorear su uso de Claude Code:

1. ccusage: Una interfaz de línea de comandos (CLI) rápida y sencilla para un análisis rápido y ad-hoc de sus datos de uso local.
2. Claude-Code-Usage-Monitor: Un panel de terminal interactivo en tiempo real que le ayuda a mantenerse al tanto de su sesión actual y evitar alcanzar los límites de tokens.
3. claude-code-otel: Una pila de observabilidad completa, de grado empresarial, para un monitoreo integral y a largo plazo del uso, rendimiento y costos de todo el equipo.

Exploraremos la arquitectura, las características y los casos de uso ideales para cada una, ayudándole a elegir la herramienta adecuada para dominar su flujo de trabajo de desarrollo con Claude Code.

ccusage

Para los desarrolladores que valoran la velocidad, la simplicidad y la eficiencia, ccusage es la herramienta perfecta. Creada por el usuario de GitHub ryoppippi, es una herramienta CLI ligera e increíblemente rápida que proporciona informes claros y concisos sobre su uso y costos de Claude Code al analizar los archivos de registro JSONL locales que genera Claude Code.

Características Clave:

• Múltiples Vistas de Informes: Obtenga información adaptada a sus preguntas con informes diarios, mensuales, de sesión y de bloques (que se alinean con las ventanas de facturación de 5 horas de Claude Code).
• Monitoreo en Vivo: Con el comando ccusage blocks --live, puede obtener un panel en tiempo real que muestra el progreso de su sesión activa, la "tasa de consumo" de tokens y los costos proyectados.
• Análisis de Costos y Modelos: La herramienta no solo cuenta tokens; los traduce a USD y puede desglosar los costos por los modelos específicos que ha utilizado (Opus, Sonnet, Haiku, etc.).
• Salida Flexible: Aunque sus tablas predeterminadas legibles por humanos están bellamente formateadas e incluso se adaptan al ancho de su terminal, también puede exportar cualquier informe a JSON con la bandera --json para una fácil integración en otros scripts o herramientas.
• Ejecución sin Dependencias: Usando npx, puede ejecutar ccusage instantáneamente sin una instalación permanente, lo que lo hace ideal para verificaciones rápidas y puntuales.

Cómo Funciona:

ccusage es una herramienta basada en NodeJS escrita en TypeScript. Su magia reside en su simplicidad. Analiza directamente los archivos .jsonl almacenados en su directorio de configuración local de Claude Code (por ejemplo, ~/.config/claude/logs/). Lee estos registros de eventos, agrega los recuentos de tokens para las indicaciones y respuestas, aplica información de precios actualizada para cada modelo y presenta los datos en un formato tabular limpio. Este enfoque de "primero lo local" significa que es increíblemente rápido y funciona completamente sin conexión (siempre que haya almacenado en caché los datos de precios una vez).

Instalación y Uso:

Empezar con ccusage no podría ser más fácil. Para una ejecución directa sin instalación, simplemente use:

npx ccusage@latest

Este comando obtendrá la última versión y le mostrará un informe diario. Para vistas más detalladas, puede especificar el tipo de informe:

# Ver un resumen del uso por cada mes
npx ccusage@latest monthly

# Agrupar el uso por sesiones de conversación
npx ccusage@latest session --breakdown

# Monitorear el bloque de facturación actual de 5 horas en tiempo real
npx ccusage@latest blocks --live

¿Para quién es?

ccusage es la herramienta ideal para el desarrollador individual. Es perfecta para:

• Responder a la pregunta: "¿Cuánto gasté en Claude Code ayer?"
• Verificar su uso de tokens al final de una larga sesión de codificación.
• Realizar análisis simples y ad-hoc sin la complejidad de una configuración compleja.
• Enviar datos de uso a otros scripts a través de su salida JSON.

Si necesita una forma rápida y sencilla de controlar su uso personal de Claude Code, ccusage es un excelente punto de partida.

Claude-Code-Usage-Monitor

Mientras que ccusage sobresale en el análisis post-mortem, Claude-Code-Usage-Monitor de Maciek-roboblog está diseñado para ser su compañero en vivo durante sus sesiones de codificación. Esta herramienta basada en Python proporciona un panel de terminal persistente y en tiempo real que no solo le muestra lo que ha usado, sino que también predice lo que va a usar, ayudándole a evitar alcanzar inesperadamente sus límites de tokens.

Características Clave:

• Panel Interactivo en Tiempo Real: El monitor proporciona una vista que se actualiza constantemente (cada 3 segundos) de su uso de tokens dentro de la ventana de sesión actual de 5 horas.
• Análisis Predictivo: Su característica destacada es el cálculo de la "tasa de consumo". Analiza su uso reciente para predecir cuándo podría agotar sus tokens para la sesión, dándole la oportunidad de reducir la velocidad.
• Barras de Progreso Visuales: La interfaz de usuario es rica e intuitiva, con barras de progreso codificadas por colores tanto para su consumo de tokens como para el tiempo restante en su sesión.
• Consciente del Plan y la Zona Horaria: Puede configurar el monitor para diferentes planes de Claude Code (Pro, Max5, Max20) y establecer su zona horaria local para predicciones precisas de reinicio de sesión. Incluso puede detectar automáticamente su plan basándose en el uso anterior.
• Sistema de Advertencia: La herramienta le alerta activamente cuando se acerca a su límite de tokens, ayudándole a gestionar su uso de forma más proactiva.

Cómo Funciona:

Similar a ccusage, esta herramienta también monitorea los archivos de registro locales de Claude Code. Sin embargo, en lugar de solo informar sobre datos pasados, mantiene un estado en vivo de su sesión actual de 5 horas. Comprende el sistema de ventana deslizante de Claude Code y calcula su uso de tokens y tasa de consumo dentro de ese contexto. Está escrita en Python y utiliza la biblioteca rich para crear su interfaz de terminal pulida e interactiva.

Instalación y Uso:

La forma recomendada de instalar Claude-Code-Usage-Monitor es usando uv, un instalador de paquetes Python moderno que maneja automáticamente los entornos virtuales.

# Instalar uv (si no lo tiene)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Instalar la herramienta
uv tool install claude-monitor

# Ejecutar el monitor
claude-monitor

Una vez en ejecución, tomará el control de su ventana de terminal y mostrará el panel en vivo. Puede personalizarlo con varias banderas:

# Especificar su plan y zona horaria
claude-monitor --plan max20 --timezone America/New_York

¿Para quién es?

Claude-Code-Usage-Monitor es para el desarrollador que desea mantenerse continuamente informado durante su trabajo. Es perfecto para:

• Usuarios en el nivel gratuito o "Pro" que tienen límites de tokens más estrictos y necesitan gestionarlos cuidadosamente.
• Desarrolladores involucrados en sesiones de codificación largas e intensivas que desean dosificar su uso.
• Cualquier persona que quiera evitar la experiencia abrupta de ser interrumpido a mitad de un pensamiento porque ha alcanzado un límite.
• Aprendices visuales que prefieren un panel gráfico a los informes estáticos.

Si desea una herramienta que actúe como un "ángel guardián" para su presupuesto de tokens, vigilándole y manteniéndole en el buen camino, esta es la indicada para usted.

claude-code-otel

Las dos primeras herramientas son fantásticas para desarrolladores individuales, pero ¿qué sucede si necesita monitorear el uso de Claude Code en todo un equipo u organización? Aquí es donde claude-code-otel de ColeMurray brilla. No es solo una herramienta; es una solución de observabilidad completa y autoalojada construida sobre componentes de código abierto estándar de la industria.

Características Clave:

• Pila de Observabilidad Completa: Proporciona una configuración preconfigurada de OpenTelemetry, Prometheus, Loki y Grafana, las mismas herramientas robustas utilizadas para monitorear la infraestructura de producción.
• Paneles Completos: El proyecto viene con paneles de Grafana preconstruidos para un análisis profundo de costos, actividad del usuario, rendimiento de la herramienta, métricas de productividad (como líneas de código cambiadas), latencia de API, errores y más.
• Monitoreo a Nivel de Equipo: Está diseñado desde cero para agregar datos de múltiples usuarios, lo que le permite ver tendencias, identificar usuarios avanzados y gestionar costos a nivel de equipo o proyecto.
• Soberanía y Seguridad de Datos: Debido a que usted aloja toda la pila, todos sus datos de uso, incluidas las indicaciones de usuario potencialmente sensibles (si elige registrarlas), permanecen dentro de su propia infraestructura.
• Basado en Estándares: Al usar OpenTelemetry, se adhiere a un estándar neutral de proveedor para datos de telemetría, lo que lo hace extensible y a prueba de futuro.

Cómo Funciona:

Esta solución adopta un enfoque fundamentalmente diferente. Aprovecha el soporte incorporado de Claude Code para OpenTelemetry (OTel). Al establecer algunas variables de entorno, puede configurar la CLI de Claude Code para emitir métricas y registros detallados. claude-code-otel proporciona una configuración de docker-compose que levanta todo el backend para recibir y procesar estos datos:

1. OpenTelemetry Collector: Recibe los datos de telemetría de todas las instancias de Claude Code de los usuarios.
2. Prometheus: Recopila y almacena las métricas (por ejemplo, recuentos de tokens, costos, latencia).
3. Loki: Ingresa y almacena los registros de eventos (por ejemplo, indicaciones de usuario, resultados de herramientas, errores de API).
4. Grafana: Consulta a Prometheus y Loki para visualizar los datos en paneles potentes e interactivos.

Instalación y Uso:

Configurar claude-code-otel es más complejo que las otras herramientas, pero está notablemente optimizado gracias a Docker.

1. Clone el repositorio:

git clone https://github.com/ColeMurray/claude-code-otel.git
cd claude-code-otel

2. Inicie la pila:

make up

3. Configure su entorno local de Claude Code para enviar datos a su nueva pila estableciendo variables de entorno:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# ... y algunas otras

4. Acceda a sus paneles navegando a http://localhost:3000 en su navegador.

¿Para quién es?

claude-code-otel es la solución definitiva para equipos de ingeniería, equipos de plataforma y la gerencia. Es ideal para:

• Organizaciones que buscan medir el ROI de sus herramientas de desarrollo de IA.
• Líderes de equipo que necesitan gestionar un presupuesto compartido para el uso de Claude Code.
• Ingenieros de plataforma que necesitan monitorear el rendimiento y la fiabilidad de las herramientas de IA.
• Cualquier organización que requiera una forma centralizada, segura y potente de entender cómo se está utilizando la IA en sus equipos de desarrollo.

Conclusión: Eligiendo Su Lente

El camino para dominar su uso de Claude Code comienza con la visibilidad. Las tres herramientas que hemos explorado ofrecen diferentes lentes a través de los cuales ver su interacción con este potente asistente de IA.

• Comience con ccusage para una forma simple, potente y rápida de obtener respuestas a preguntas comunes sobre su uso pasado.
• Pase a Claude-Code-Usage-Monitor cuando quiera pasar del análisis reactivo a la gestión proactiva y en tiempo real de su presupuesto de tokens durante sus sesiones de codificación.
• Adopte claude-code-otel cuando su enfoque cambie del uso individual a la observabilidad a nivel de equipo, la gestión de costos y el análisis de rendimiento.

Cada uno de estos proyectos de código abierto representa una fantástica contribución a la comunidad de desarrolladores, empoderando a los usuarios para pasar de ser consumidores pasivos de tecnología de IA a participantes activos e informados. Al elegir la herramienta adecuada para sus necesidades, puede desbloquear un nuevo nivel de control y conocimiento, asegurándose de obtener el máximo valor de su flujo de trabajo de desarrollo asistido por IA.