¡Controla tu Claude Code en vivo! Monitor en tiempo real
Un desarrollador construyó desde cero, usando exclusivamente Claude Code en una sola sesión, un monitor de uso en tiempo real para los límites de la API de Anthropic. La herramienta, publicada como código abierto en GitHub bajo licencia MIT, muestra tokens consumidos, predicciones de agotamiento y alertas desde el system tray, cubriendo el hueco que dejó la interfaz oficial de claude code.
En 30 segundos
- Claude-Code-Usage-Monitor es una herramienta Python open source, disponible en PyPI, que muestra en tiempo real cuántos tokens te quedan en tu sesión activa de Claude Code.
- Los límites de Claude operan en ventanas de 5 horas (desde el primer mensaje), con cuotas adicionales semanales que Anthropic no documenta con precisión pública.
- Claude Code tiene comandos nativos:
/usage,/stats,/costy/context, pero son menos detallados que las herramientas especializadas. - Para equipos, existe claude-code-otel, que exporta telemetría vía OpenTelemetry hacia Grafana o Datadog.
- ccusage es la alternativa CLI más liviana para quienes no necesitan interfaz gráfica.
¿Por qué es difícil monitorear el uso de claude code?
Ponele que estás en medio de una sesión intensa: le pedís a Claude Code que refactorice un módulo grande, lo ejecuta, vos aprobás cambios, pedís más, y de repente el modelo te corta con un mensaje de límite alcanzado. No sabías que estabas cerca. No había ningún indicador visible. Todo el contexto acumulado de esa sesión queda flotando mientras esperás que la ventana se resetee.
Eso pasa porque la interfaz oficial de Anthropic no tiene un panel nativo que muestre en tiempo real los tokens consumidos. Lo que existe son mensajes de error cuando ya te quedaste sin cuota. No es lo mismo.
El sistema de límites de Claude Code usa ventanas de 5 horas que arrancan con el primer mensaje de la sesión, con cuotas por plan que varían entre modelos, y Anthropic aplica también límites semanales adicionales que no están documentados con precisión pública. Según el centro de ayuda de Anthropic, los límites exactos dependen del plan contratado y de la carga del sistema en ese momento. “Depende del sistema” es exactamente el tipo de respuesta que te deja sin herramientas para planificar.
Sistema de límites de Claude: ventanas, tokens y cuotas
Claude Code es la herramienta CLI de Anthropic que permite a los desarrolladores interactuar con Claude directamente desde la terminal para tareas de programación, con acceso directo a archivos, comandos y contexto del proyecto.
El cálculo de consumo tiene varias capas. Cada mensaje usa tokens de entrada (tu prompt, el contexto del proyecto, los archivos incluidos) y tokens de salida (la respuesta de Claude). Los modelos más capaces (Opus) consumen más cuota por token que Haiku o Sonnet. Y si usás herramientas como lectura de archivos o ejecución de comandos, eso también suma al conteo.
La ventana de 5 horas es el límite más importante para entender. No importa cuántas sesiones abras: si empezaste a usar Claude a las 10:00, la ventana se resetea a las 15:00, independientemente de cuántos terminales tengas abiertos. Muchos usuarios asumen que “cerrar y abrir” resetea el contador. No lo hace. Cubrimos ese tema en detalle en cómo gestionar claves de API de forma segura.
Para el plan Pro, los límites son más altos pero igual finitos, y Anthropic puede ajustarlos según demanda del sistema. En abril de 2026 hubo reportes de usuarios que vieron sus mensajes agotarse más rápido de lo habitual, lo que sugirió ajustes no anunciados en los límites del plan Pro.
Tres herramientas open source para monitorear tu uso
El ecosistema se movió rápido para cubrir el hueco que dejó Anthropic. Hoy hay tres opciones serias, con perfiles muy distintos.
Claude-Code-Usage-Monitor: la opción con más features
Desarrollada por Maciek-roboblog y disponible en GitHub, esta herramienta Python ofrece un dashboard interactivo construido con la librería Rich. Tiene tres vistas: tiempo real, uso diario y uso mensual. Lo interesante es que incluye predicciones por machine learning: el sistema calcula cuándo vas a agotar la cuota basándose en tu ritmo de consumo actual. También tiene iconos en el system tray del sistema operativo, con colores que cambian según el porcentaje restante.
La instalación es directa:
pip install claude-monitor
# o con uv:
uv tool install claude-monitorLicencia MIT. Funciona leyendo los logs locales que Claude Code genera en tu máquina, sin necesidad de conectarse a la API de Anthropic.
ccusage: CLI minimalista para quien no necesita pantallas
ccusage toma el mismo enfoque de leer logs locales pero en formato de línea de comandos, sin interfaz gráfica. Instalación con npm, output limpio, y se integra bien en scripts o en pipelines de CI donde querés chequear el estado antes de lanzar una tarea pesada. Para desarrolladores que viven en la terminal y no quieren otra ventana abierta, es la opción más práctica.
claude-code-otel: para equipos que monitorean en serio
Si manejás un equipo de cinco o más personas usando Claude Code, las soluciones anteriores se quedan cortas. claude-code-otel exporta métricas vía OpenTelemetry hacia cualquier plataforma de observabilidad (Grafana, Datadog, lo que ya tengas). Permite ver series temporales de consumo por usuario, configurar alertas cuando un miembro del equipo está por agotar su cuota, y correlacionar el gasto en tokens con los eventos del sistema. No tiene interfaz propia: asume que ya tenés infraestructura de monitoreo.
El proyecto de Maciek: construido enteramente con Claude Code
Lo que hace interesante a Claude-Code-Usage-Monitor más allá de sus features es el proceso de construcción. El desarrollador documentó que creó la herramienta entera en una sola sesión de Claude Code, sin escribir código manualmente. Claude generó la estructura del proyecto, las clases de parsing de logs, la integración con Rich para el dashboard, y las predicciones de ML.
¿El resultado? Una herramienta que monitorea los límites de Claude… construida usando Claude hasta sus propios límites. (La ironía está ahí, no hace falta subrayarla.)
El proyecto tiene vistas separadas para uso en tiempo real, acumulado diario y mensual, lo que es útil para distinguir entre “me estoy pasando hoy” y “este mes consumí más de lo habitual”. El indicador del system tray pasa de verde a amarillo a rojo según el porcentaje restante de cuota, sin que tengas que tener el dashboard abierto.
Comandos nativos de Claude Code: qué tenés sin instalar nada
Antes de instalar herramientas de terceros, conviene saber qué viene incluido. Claude Code tiene cuatro comandos relevantes: Esto se conecta con lo que analizamos en exponer herramientas CLI como servicios API.
- /usage: muestra los límites del plan y cuánto consumiste en la ventana actual.
- /stats: panel completo con heatmap de uso, rachas de trabajo y estadísticas históricas.
- /cost: muestra el costo estimado de la sesión actual en dólares.
- /context: desglose del contexto de la sesión actual, con cantidad de tokens usados por cada archivo o herramienta incluida.
La ventaja es obvia: no requieren instalación, están siempre disponibles, y /context es especialmente útil para entender por qué una sesión está consumiendo tanto (a veces metiste un archivo enorme sin darte cuenta).
La limitación es que son snapshots manuales. No actualizan en tiempo real mientras trabajás, y no te avisan antes de que te quedes sin cuota.
Monitoreo para equipos con OpenTelemetry
Un equipo de desarrollo que usa Claude Code de forma intensiva necesita visibilidad diferente a la de un desarrollador individual. Las preguntas cambian: no es “¿cuánto me queda a mí?” sino “¿quién del equipo está consumiendo más?”, “¿qué tarea generó ese pico?”, “¿en qué momento del sprint se gasta más cuota?”.
claude-code-otel responde esas preguntas exportando trazas y métricas en el estándar OpenTelemetry, que cualquier plataforma de observabilidad moderna acepta. Si tu equipo ya usa Grafana o Datadog para monitorear microservicios, podés agregar el consumo de Claude Code como otro dashboard sin infraestructura adicional. Podés configurar alertas que disparen cuando algún miembro del equipo está al 80% de su cuota diaria, antes de que se corte.
Para proyectos que usan Claude Code en CI/CD (por ejemplo, revisión automática de PRs), esto pasa de “nice to have” a necesario.
Tabla comparativa de herramientas
| Herramienta | Tipo | Instalación | Tiempo real | Predicciones | Para equipos | Licencia |
|---|---|---|---|---|---|---|
| Claude-Code-Usage-Monitor | Dashboard GUI | pip/uv | Sí | Sí (ML) | Limitado | MIT |
| ccusage | CLI | npm | Manual | No | No | Open source |
| claude-code-otel | Telemetría | npm + backend OTel | Sí | No nativo | Sí | Open source |
| /usage (nativo) | Comando CLI | Sin instalación | Snapshot | No | No | Incluido |
Mejores prácticas para no alcanzar el límite en el peor momento
Hay cosas que consumir un token innecesario no justifica y que con un poco de orden se evitan. Relacionado: automatización inteligente en tus workflows.
Lo primero: chequeá /context antes de arrancar una tarea pesada. Si ves que el contexto de la sesión ya tiene 80.000 tokens, abrí una sesión nueva en vez de seguir acumulando en la misma. Las sesiones con contexto muy grande consumen más tokens por mensaje porque Claude tiene que procesar todo ese contexto en cada respuesta.
Después está la cuestión de los archivos. Claude Code incluye automáticamente archivos referenciados en el contexto, y si metés un archivo de 5.000 líneas para preguntar sobre una función de 20 líneas, pagás por los 5.000. Aprendé a usar las instrucciones de contexto selectivo.
Para trabajo distribuido en varios días: terminá las sesiones activas cuando no las estés usando. La ventana de 5 horas corre igual aunque no escribas mensajes, pero el contexto acumulado no consume hasta que mandás el siguiente mensaje. Dicho esto, cerrar la sesión limpia el contexto y te da un punto de partida más eficiente para la siguiente.
Si usás Claude-Code-Usage-Monitor, configurá la alerta del system tray para que cambie a rojo al 30% restante, no al 10. Al 10% ya es tarde para terminar algo complejo.
Errores comunes al monitorear uso de Claude
Confundir mensajes con tokens. El límite no es de “mensajes”, es de tokens. Un mensaje de 50 palabras y un mensaje que adjunta tres archivos de código cuentan diferente. Muchos usuarios calculan mal cuánto les queda basándose en cantidad de intercambios.
Asumir que cambiar de modelo resetea la cuota. Si pasás de Sonnet a Haiku a mitad de sesión, no reiniciás la ventana de 5 horas. Haiku consume menos tokens por mensaje, pero la cuota de tiempo sigue corriendo desde el primer mensaje de la sesión, independientemente del modelo. Más contexto en asegurar el código en tus pipelines.
No separar uso interactivo de uso en scripts. Si tenés scripts que llaman a Claude Code automáticamente (para revisar PRs, por ejemplo), esos consumen cuota de la misma ventana que tu trabajo manual. Sin monitoreo, es fácil llegar al horario de trabajo con la cuota ya medio consumida por procesos automáticos nocturnos.
Esto se conecta con I built a real-time Claude usage limit monitor — entirely wi, donde profundizamos más sobre el tema.
Mirá I built a real-time Claude usage limit monitor — entirely wi si querés más detalles sobre esto.
Si querés ver una implementación real, acá está I built a real-time Claude usage limit monitor — entirely wi.
Preguntas Frecuentes
¿Cómo monitoreo mi uso de Claude Code en tiempo real?
La opción más completa es Claude-Code-Usage-Monitor, instalable con pip install claude-monitor. Muestra tokens restantes, predicciones de agotamiento y un indicador en el system tray. Para una alternativa más simple sin interfaz gráfica, ccusage funciona desde la terminal con instalación vía npm. Si no querés instalar nada, el comando nativo /usage dentro de Claude Code muestra el estado actual, aunque es un snapshot manual.
¿Cuántos tokens me quedan en Claude y cómo lo sé?
Anthropic no expone un contador público en tiempo real, pero sí podés verlo con /context (contexto de la sesión actual) y /usage (cuota del plan). La cantidad exacta disponible depende de tu plan (Free, Pro, Team, Enterprise) y del modelo que estés usando. Claude-Code-Usage-Monitor calcula la cuota restante leyendo los logs locales de la aplicación y cruzándolos con los parámetros del plan.
¿Cómo funciona la ventana de sesión de 5 horas en Claude?
La ventana de 5 horas arranca con el primer mensaje que enviás y se resetea automáticamente al vencer ese plazo, independientemente de cuántos mensajes hayas mandado. No se resetea por cerrar la sesión ni por cambiar de modelo. Anthropic usa este sistema para distribuir la carga del servicio, y puede aplicar límites adicionales semanales según el plan contratado.
¿Cuál es la mejor herramienta para monitorear uso de Claude Code en equipos?
Para equipos de desarrollo, claude-code-otel es la opción más adecuada. Exporta métricas vía OpenTelemetry hacia plataformas como Grafana o Datadog, permitiendo ver consumo por usuario, configurar alertas preventivas y correlacionar el gasto en tokens con eventos del sistema. Las herramientas individuales como Claude-Code-Usage-Monitor o ccusage no tienen soporte multi-usuario.
¿Cómo evitar alcanzar el límite de sesión de Claude en el peor momento?
Tres prácticas concretas: revisá /context antes de tareas pesadas y abrí sesión nueva si el contexto ya es grande; separé los scripts automáticos que llaman a Claude de tu trabajo manual para no compartir cuota; configurá la alerta de Claude-Code-Usage-Monitor al 30% restante, no al 10%. Distribuir el trabajo en sesiones más cortas también ayuda, ya que cada nueva sesión empieza con contexto limpio.
Conclusión
El hueco era claro: Anthropic lanzó Claude Code con límites de uso reales pero sin herramientas nativas para monitorearlos antes de agotarlos. La comunidad lo cubrió con tres proyectos open source que hacen cosas distintas: Claude-Code-Usage-Monitor para quienes necesitan un dashboard visual con predicciones, ccusage para quienes viven en la terminal, y claude-code-otel para equipos que ya tienen infraestructura de observabilidad.
El hecho de que la herramienta más completa haya sido construida enteramente con Claude Code en una sola sesión dice algo sobre el estado actual de la herramienta: es lo suficientemente capaz como para construir sus propios monitores de límite. (Lo que no resuelve el problema de quedarte sin cuota a mitad del proceso de construcción.)
Si usás Claude Code de forma regular, instalá al menos una de estas herramientas. No necesitás el dashboard completo: ccusage en tres segundos ya es mejor que enterarte del límite por un error inesperado.
