¡Controla tu Claude Code en vivo! Monitor en tiempo real

Actualizado el 02/09/2026 — Reescritura mayor del artículo con nuevas secciones, datos actualizados y cobertura completa de las queries de búsqueda sobre monitoreo de consumo en Claude Code.

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.

Claude Code Usage Monitor es una herramienta Python open source que rastrea en tiempo real cuántos tokens consumís en tu sesión activa de Claude Code. Lee los logs locales de la aplicación sin conectarse a Anthropic, mostrando consumo actual, predicciones por machine learning sobre cuándo agotarás la cuota, e indicadores visuales en el system tray del SO. Funciona en planes Free, Pro, Max5 y Max20. Se instala con pip install claude-monitor y está disponible bajo licencia MIT en PyPI y GitHub. También existen alternativas especializadas: ccusage para CLI minimalista, claude-code-otel para equipos con infraestructura de observabilidad, y comandos nativos (/usage, /stats, /context) incluidos en la interfaz de Claude Code sin necesidad de instalar nada.

¿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 Claude Code no tiene un panel nativo que muestre en tiempo real los tokens consumidos mientras trabajás. Lo que existe son mensajes de error cuando ya te quedaste sin cuota. No es lo mismo: enterarte por error es muy distinto a tener visibilidad proactiva.

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.

Cómo funcionan los 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 total.

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. La ventana corre en paralelo a la ejecución de la interfaz: si cerrás Claude Code, el temporizador sigue contando.

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.

Dónde ver tu consumo de tokens en Claude Code

Antes de instalar herramientas de terceros, conviene saber qué información te da Claude Code nativamente sin configurar nada. Hay cuatro comandos que podés ejecutar directamente en cualquier sesión:

• /usage: Muestra los límites totales de tu plan y exactamente cuántos tokens consumiste en la ventana de 5 horas actual. Es el comando más directo para responder “¿cuántos me quedan?”. La salida te da un número: tokens restantes de 100.000, por ejemplo.
• /stats: Panel más completo con un heatmap visual de tu uso a lo largo del tiempo, rachas de trabajo intenso, y estadísticas históricas por día y por semana. Util si querés ver patrones (por ejemplo, si siempre consumís más a cierta hora).
• /cost: Muestra el costo estimado de la sesión actual en dólares, desglosado por modelo si usaste varios. Ayuda a conectar tokens con dinero gastado.
• /context: Desglose exacto del contexto que tenés cargado en tu sesión: cuántos tokens ocupa cada archivo, las herramientas incluidas, y el prompt del sistema. Muy útil para entender por qué una sesión quema tantos tokens (a veces metiste un archivo de 500 KB sin darte cuenta).

Estos comandos funcionan desde cualquier cliente de Claude Code (CLI, VS Code, desktop app). Ejecutalos cuando necesites un snapshot rápido.

La limitación principal es que son snapshots manuales. No actualizan en tiempo real mientras trabajás, no te avisan antes de que te quedes sin cuota, y si estás en el flujo de escribir código, interrumpir para ejecutar /usage cada 5 minutos mata la productividad. Por eso existen las herramientas open source que monitorean continuamente en el background.

Tres herramientas open source para monitorear tu uso en tiempo real

El ecosistema se movió rápido para cubrir el hueco que dejó Anthropic. Hoy hay tres opciones serias, cada una con un perfil distinto según tu caso de uso.

Claude-Code-Usage-Monitor: dashboard interactivo con predicciones

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, sin esperar a que Anthropic te corte.

También tiene iconos en el system tray del SO (Windows, macOS, Linux), con colores que cambian según el porcentaje restante: verde cuando tenés abundancia, amarillo al 50%, rojo al 30%. Sin que tengas que tener el dashboard abierto, ves de un vistazo si estás seguro o en riesgo.

La instalación es directa:

pip install claude-monitor
# o con uv:
uv tool install claude-monitor

Funciona leyendo los logs locales que Claude Code genera en tu máquina, sin necesidad de conectarse a la API de Anthropic. Licencia MIT. Disponible también en PyPI como `claude-monitor`.

ccusage: CLI minimalista sin interfaz gráfica

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 estructurado, se integra bien en scripts o 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. Además, porque es CLI puro, se puede invocar desde scripts automáticos que monitoreen uso desatendido.

claude-code-otel: telemetría para equipos grandes

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. Es la opción para empresas que necesitan rigor en el tracking de recursos.

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 hasta sus propios límites.

¿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. Y la utilidad también: si Claude pudo generar esto en una sesión, significa que la herramienta es lo suficientemente buena como para resolver un problema real.

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.

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.

Configurar alertas automáticas es clave en equipos: una alerta que dispare cuando algún miembro está al 80% de su cuota diaria te avisa ANTES de que se corte, en vez de recibir el error post-facto. Para proyectos que usan Claude Code en CI/CD (por ejemplo, revisión automática de PRs o generación de código), esto pasa de “nice to have” a necesario.

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.

• Chequeá /context antes de tareas pesadas. Si ves que el contexto de la sesión ya tiene 80.000 tokens cargados, abrí una sesión nueva. Las sesiones con contexto muy grande consumen más tokens por mensaje porque Claude tiene que procesar todo ese contexto en cada respuesta. A veces un archivo de código que incluiste tiene 500 KB sin que te hayas dado cuenta.
• Sé selectivo con los archivos. Claude Code incluye automáticamente archivos referenciados en el contexto. 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. Aprende a usar filtros y selecciones de rango de líneas en vez de adjuntar el archivo entero.
• Terminá sesiones activas cuando no las uses. La ventana de 5 horas corre igual aunque no escribas mensajes, pero el contexto acumulado no consume tokens 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. Algunas tareas grandes se resuelven mejor en 2-3 sesiones cortas que en 1 sesión gigante.
• Configurá alertas del system tray al 30%, no al 10%. Si usás Claude-Code-Usage-Monitor, cambiá el threshold de rojo a 30% restante, no a 10%. Al 10% ya es tarde para terminar algo complejo: estás apurado para enviar el último mensaje y cerrar. Al 30% tenés tiempo para guardar contexto importante o esperar el reset sin frenar el flujo.
• Separá trabajo interactivo de trabajo automático. Si tenés scripts que llaman a Claude Code automáticamente (revisión de PRs en CI, 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 nocturnos. Considerá usar horarios distintos o ventanas separadas.
• Registrá tu consumo por proyecto. Si trabajás en varios proyectos, entender cuál consume más te ayuda a priorizar. Algunos refactors pesados de arquitectura queeman la ventana en 40 minutos; otros, cambios minimalistas, apenas 8.000 tokens. Conocer el perfil de cada proyecto te ayuda a planificar sesiones de forma realista.

Troubleshooting: Errores comunes cuando chequeas consumo

Algunos problemas frecuentes que los usuarios reportan al monitorear uso:

• El comando /usage muestra 0 tokens consumidos. Paso: cerrá y reabrí Claude Code. A veces el comando captura un estado inconsistente si acabás de mandar un mensaje y Claude aún está procesando. Esperá 30 segundos y reintentá.
• Claude-Code-Usage-Monitor no aparece en el system tray. Verificá que la instalación completó sin errores: pip show claude-monitor debe retornar versión 1.x.x. Si falta, desinstalá con pip uninstall claude-monitor y reinstalá con pip install claude-monitor --upgrade. En Windows, algunos firewalls bloquean las notificaciones del tray; deshabilitá el firewall de Windows temporalmente para testear.
• La predicción de agotamiento en el monitor es inconsistente. Las predicciones por ML se calibran después de los primeros 3-5 mensajes. Si acabás de iniciar una sesión y ves una predicción rara (diciendo que te quedan 15 minutos cuando apenas consumiste), ignorala hasta que el monitor haya visto más datos. El modelo se estabiliza después.
• /context reporta más tokens de los que esperaba. Cosas que pesa tokens: prompt del sistema (siempre está), todos los archivos abiertos o referenciados (aunque no hayas interactuado con ellos), el historial de la sesión completo (cada mensaje tuyo + respuesta de Claude). Una sesión de 20 intercambios puede tener 50.000+ tokens de contexto acumulado, aunque hayas escrito 500 palabras en total.

Errores comunes de interpretación 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. Porque el límite es realmente de tokens, las herramientas open source que leen los logs son mucho más precisas que contar “cuántos mensajes mandé”.

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, eso es cierto, pero la cuota de tiempo sigue corriendo desde el primer mensaje de la sesión, independientemente del modelo. Lo que sí cambia es la velocidad de consumo: Haiku frena el burn rate, pero no detiene el reloj.

No separar uso interactivo de uso en scripts. Si tenés scripts que llaman a Claude Code automáticamente (para revisar PRs, generar documentación, etc.), 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.

Olvidar que el contexto de la sesión persiste. Cada mensaje que mandás, Claude ve TODO lo que pasó antes en esa sesión. Un proyecto con 50.000 líneas de código referenciado significa que cada mensaje paga por esas 50.000 líneas nuevamente. El contexto no se “limpia” entre mensajes: se acumula.

Preguntas Frecuentes

¿Dónde veo exactamente cuántos tokens me quedan en Claude Code?

Ejecutá el comando /usage en cualquier sesión de Claude Code (CLI, VS Code, desktop app). Te muestra de inmediato los tokens restantes de tu plan y cuántos consumiste en la ventana actual. Para una visión más detallada (histórico y predicciones), instalá Claude-Code-Usage-Monitor con pip install claude-monitor: luego verás un dashboard completo más indicador en el system tray.

¿Cuáles son exactamente los límites de Claude Code por plan?

Claude Code usa ventanas de 5 horas desde el primer mensaje, con cuotas semanales adicionales que Anthropic no documenta públicamente. Los límites exactos varían según tu plan (Pro vs Free) y la carga del sistema en ese momento. El consumo también depende del modelo: Opus consume más cuota que Sonnet o Haiku. Para los números precisos de tu plan específico, ejecutá /usage dentro de Claude Code; ahí ves la cuota total disponible y cuánto consumiste.

¿Cómo instalo claude-monitor?

Instalá Claude-Code-Usage-Monitor con pip install claude-monitor o, si usás uv, con uv tool install claude-monitor. Es la herramienta más completa: muestra uso en tiempo real, hace predicciones por machine learning, y lanza alertas desde el system tray. Disponible bajo licencia MIT en PyPI.

¿Necesito credenciales de Anthropic para instalar claude-monitor?

No. Se instala directamente con pip install claude-monitor sin requerir API keys ni credenciales de Anthropic. Lee los logs locales que Claude Code ya genera en tu máquina, sin conectarse a internet ni a servidores de Anthropic.

¿Cuál es la diferencia entre /usage y claude-monitor?

El comando nativo /usage te da un snapshot manual cuando lo ejecutás: ves los números exactos de consumo en ese instante. claude-monitor muestra monitoreo continuo en tiempo real con predicciones de ML sobre cuándo agotarás la cuota, todo desde una ventana independiente sin interrumpir tu trabajo. /usage es para chequeos puntuales; claude-monitor es para vigilancia constante.

¿Qué es la ventana de 5 horas y cómo la reinicio?

Es el período desde tu primer mensaje hasta 5 horas después, cuando se resetea tu cuota de tokens automáticamente. No se reinicia cerrando Claude Code ni cambiando de modelo: corre en segundo plano aunque no uses la aplicación. Solo esperá hasta pasadas las 5 horas desde el primer mensaje de esa sesión. Si necesitás una cuota limpia urgentemente, no hay shortcut: hay que esperar el reset natural.

¿Cómo monitoreo mi uso de Claude Code si trabajo en un equipo?

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 nativo.

¿Cómo evito 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 (80.000+ tokens); separé los scripts automáticos que llaman a Claude de tu trabajo manual para no compartir cuota; configurá la alerta de claude-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 y cuota fresca.

¿Qué hace el comando /context exactamente?

Muestra un desglose exacto de cuántos tokens estás usando actualmente en la sesión por cada fuente: el prompt del sistema, cada archivo abierto o referenciado, el historial de mensajes de esa sesión. Es útil cuando una sesión te quema tokens más rápido de lo esperado y querés identificar qué está ocupando espacio. A veces un archivo de código de 2 MB que olvidaste que estaba abierto puede estar consumiendo 40.000 tokens por mensaje.

¿Puedo usar claude-monitor en CI/CD para monitorear gastos automáticos?

Sí, pero es más fácil hacerlo con ccusage (CLI) que integrás en tus scripts de CI, o configurar claude-code-otel si tenés infraestructura de observabilidad. claude-monitor está diseñado para monitoreo interactivo (usuario presente), así que en CI/CD es mejor usar las alternativas CLI que se invocan bajo demanda.

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, o simplemente el comando /usage, ya es mejor que enterarte del límite por un error inesperado a mitad de una tarea crítica.

Fuentes

• Claude-Code-Usage-Monitor en GitHub — repositorio oficial del proyecto
• Anthropic Support — cómo funcionan los límites de uso y longitud
• ccusage — herramienta CLI para monitoreo de uso
• claude-code-otel en GitHub — monitoreo con OpenTelemetry