Monitor de uso de Claude Code: rastreador en tiempo real para evitar límites de uso

• Herramienta de monitoreo que muestra en tiempo real en la terminal información variada como el uso de tokens de Claude AI, la velocidad de consumo y la predicción de agotamiento
• Barras de progreso coloridas que se actualizan cada 3 segundos, con predicción inteligente del agotamiento de tokens
• Si se supera el límite del plan base, analiza el historial de sesiones para cambiar de inmediato al límite real
• Detecta y soporta automáticamente planes de uso como Pro/Max5/Max20/custom_max
• Alertas en tiempo real cuando el límite de tokens por sesión está cerca o se supera, o cuando hay riesgo de agotamiento antes del reinicio de la sesión
• Interfaz implementada y optimizada para el flujo real de uso de Claude
• Instalación con npm, pip, se recomienda usar entornos virtuales (venv/virtualenv), compatible con Mac/Linux/Windows

Entender las sesiones de Claude

• Modelo de ventana móvil de 5 horas
  • La sesión se mantiene durante 5 horas desde el momento en que se envía el primer mensaje
  • El límite se aplica por sesión y pueden coexistir varias activas al mismo tiempo
  • El reinicio real ocurre cada 5 horas según el momento de mis mensajes
• Es posible definir la hora de reinicio de sesión/tokens según mi propio horario

Escenarios de uso

• Desarrolladores que empiezan por la mañana: pueden ajustar el horario de reinicio de tokens al inicio de la jornada (por ejemplo, a las 9) para planificar de forma más eficiente
• Quienes trabajan de noche: pueden usar un reinicio de tokens adaptado a su horario, por ejemplo a medianoche
• Usuarios con límites variables: en modo custom_max, el límite se detecta automáticamente según el entorno real
• Desarrolladores globales/remotos: mover el horario de reinicio entre varias zonas horarias o definirlo a nivel de equipo → optimiza la colaboración
• Verificación rápida del estado: ejecución simple (sin importar la configuración)

Mejores prácticas para preparar el entorno

• Iniciar el monitoreo al mismo tiempo que la sesión
  • Ejecuta el monitor en cuanto empieces a trabajar con Claude (./ccusage_monitor.py)
  • Planes compatibles
    • pro: aprox. 7,000 tokens (pruebas y uso ligero)
    • max5: aprox. 35,000 tokens (desarrollo cotidiano)
    • max20: aprox. 140,000 tokens (proyectos grandes y uso medio/intensivo)
    • custom_max: modo de detección automática (usa el valor máximo según el historial real de uso)
  • Mejora la precisión del seguimiento de tokens durante toda la sesión
  • Permite calcular la velocidad de consumo de tokens y emitir alertas tempranas cuando se acerca el límite
• Usar un entorno virtual de Python (venv)
  • Evita conflictos de dependencias, separa entornos y garantiza reproducibilidad por proyecto
  • Instalación y ejecución:

    python3 -m venv venv  
    source venv/bin/activate  
    pip install pytz  
    

  • Para eliminarlo limpiamente, basta con borrar la carpeta del entorno virtual
• Registrar un alias personalizado del shell
  • Acorta comandos repetitivos para ejecutarlos en una sola línea

    alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./ccusage_monitor.py'  
    

  • Añádelo a .bashrc o .zshrc para lanzar el monitor de inmediato con un solo comando

Mejores prácticas de uso

• Monitorear siempre el Burn Rate (velocidad de consumo)
  • Ten cuidado si el uso de tokens se dispara de repente
  • Ajusta la intensidad del trabajo según el tiempo y la cantidad de tokens restantes
  • Programa tareas grandes, como refactorizaciones masivas, antes o después del reinicio de sesión (reinicio de tokens)
• Programación estratégica de sesiones
  • Inicia las tareas grandes justo después del reinicio de tokens y deja las tareas ligeras para cuando el límite esté cerca

    ./ccusage_monitor.py --reset-hour 9  
    

  • Puedes operar varias sesiones superpuestas aprovechando la regla de 5 horas por sesión
• Especificar claramente la zona horaria
  • Refleja tu horario real de trabajo/colaboración para prever con precisión el reinicio de tokens y organizar mejor las tareas

    ./ccusage_monitor.py --timezone Asia/Seoul  
    

  • Evita desfases de tiempo y minimiza la confusión sobre el vencimiento de sesiones al colaborar con varios países o equipos

Consejos de optimización

• Configuración del entorno de terminal
  • Se recomienda una terminal de al menos 80 caracteres de ancho
  • El soporte de color maximiza la retroalimentación visual
  • Se recomienda mantener el monitoreo siempre activo en una ventana dedicada
• Integración en el flujo de trabajo
  • Puedes monitorear mientras desarrollas usando un multiplexor de terminal como tmux

    tmux new-session -d -s claude-monitor './ccusage_monitor.py'  
    tmux attach -t claude-monitor  
    

• Estrategia multi-sesión
  • Cada sesión dura 5 horas fijas y es posible administrar varias sesiones superpuestas al mismo tiempo
  • Distribuye trabajos largos entre varias sesiones, prestando atención al límite y al vencimiento de cada una

Ejemplos de flujo de trabajo real

• Desarrollo de proyectos grandes

  ./ccusage_monitor.py --plan max20 --reset-hour 8 --timezone America/New_York  
  

  • Reinicio de tokens a las 8 a. m. → inicio del desarrollo de funciones principales
  • A las 10, revisar el Burn Rate y ajustar el ritmo de trabajo
  • A las 12, revisar y ajustar la agenda de la tarde
  • A las 14, abrir una nueva sesión y abordar temas complejos
  • A las 16, preparar trabajo ligero o la sesión de la noche
• Uso centrado en aprendizaje/experimentos

  ./ccusage_monitor.py --plan pro  
  

  • Adecuado para aprendizaje ligero y escritura de código experimental
• Desarrollo intensivo para sprint

  ./ccusage_monitor.py --plan max20 --reset-hour 6  
  

  • Configuración adaptada para desarrollos donde se espera un consumo intensivo y alto de tokens

[fanotify]

Es lo mismo: https://es.news.hada.io/topic?id=21560

[GN⁺]

Opinión en Hacker News

• Comparto que me frustra la falta de transparencia de Claude y que esta idea me gusta mucho La función clave de Claude Code, comparado con la app de escritorio, es que puede gestionar mejor el contexto y los límites (por ejemplo, modo compact, mostrar el % de capacidad restante), pero aun así da la sensación de que no es suficiente Como consejo adicional, en lo personal siento que usar demasiados emojis en el README de un proyecto se ve muy poco profesional, y me hace pensar que es un proyecto codificado más por “vibra” que con una gestión adecuada de la IA

  • Cuando yo entré al mundo del software, si te cachaban usando emojis en una base de código, era como para mandarte al manicomio Ahora los tiempos cambiaron muchísimo, y uso emojis seguido para organizar visualmente el contexto Ahora mi código tiene suficientes emojis como para hacerme feliz

  • Últimamente se ve mucho este estilo con emojis en startups o empresas jóvenes Probablemente por la influencia de Notion En nuestra empresa siempre estamos eligiendo emojis, ya sea para hacer una lista, una página o hasta una invitación de calendario

  • Me parece bastante irónico que dejen este tipo de comentarios sobre software hecho para programar con IA

  • Si ves el código de verdad, solo envuelve ccusage en un único archivo de Python de 400 líneas Así que entiendo por qué alguien podría sentirlo así

  • Para descripciones de PR o README generados por IA, siempre agrego en el prompt una condición tipo “sé conciso, sin adornos floridos ni emojis” Con eso, la fiesta caótica de emojis se convierte en documentación decente Aunque puede variar según el caso

• Soy el creador de ccusage, y me da gusto ver que la gente use nuestro open source de distintas maneras ¡Happy vibe coding!

  • Curiosamente, el Show HN de ccusage no tiene ni un solo comentario, pero este hilo está muy activo, lo cual da risa Enlace al hilo relacionado

• Como referencia, el límite máximo de tokens en una sesión pasada mía fue de unos 337,492, y uso el plan Max20 y Opus en alrededor de un 99% Uso Claude Code desde el 27 de mayo, y en total he consumido 1,374,439,311 tokens, que equivalen a unos 3,397 dólares

  • Yo he usado como unos 2,100 dólares con el plan Max20 Me pregunto si la API deja un margen enorme o si en realidad están perdiendo dinero La uso todos los días, pero no siento que la use de forma excesiva

  • Me pregunto si no te topas seguido con limitaciones de velocidad en Opus, o si no sientes que es más lento que Sonnet

• Puedo intuir bastante bien qué tan cerca estoy del límite según la cantidad de tokens que llevo usados También detecto cuándo la conversación misma está por llegar al máximo, y en ese momento uso los últimos recursos disponibles para generar un resumen y seguir trabajando en un chat nuevo Siento que estas herramientas de IA ya se volvieron parte de mi reloj biológico Cada miércoles se reinicia el límite semanal de ChatGPT, así que el miércoles se siente como un nuevo domingo

• He observado que si el uso de tokens no llega al 100% antes de que pase la ventana de tiempo, no se reinicia Por ejemplo, si usas 90% y pasas a la siguiente ventana, luego consumes rápido el 10% restante, te toca esperar muchísimo tiempo

• Yo hice una herramienta de UI (crystal) para poder usar varias sesiones de Claude Code al mismo tiempo Como trabajo varias funciones a la vez, seguido llego al límite de mi cuenta Normalmente alcanzo el límite cerca de la hora de reinicio, pero estaría mejor poder saber de antemano cuándo conviene tomar un descanso

  • Uso muchísimo Claude Code, pero me frena que no entiendo git lo suficiente como para animarme a crear tooling para worktree y trabajo con varias sesiones La verdad, hasta me da un poco de miedo usar esta herramienta, e idealmente me gustaría correr cada worktree en un contenedor, pero siento que sería difícil lograr que funcione tan fluido como Crystal

  • Me gusta esta herramienta, pero Crystal me confunde porque ya era el nombre de un lenguaje de programación que usé hace tiempo

  • Si dejas un issue en GitHub (aquí), también puedo intentar integrarlo con mi usage monitor

  • Está buenísimo Yo también casi le habría pedido a Laude algo así, no por proyecto sino para 5 proyectos simultáneos Coincido en que hay muchísimas oportunidades de uso

• Está muy interesante, pero me pregunto si el límite de tokens del plan Pro de verdad es de apenas 7,000 O sea, ni siquiera serían 7,000 palabras, pero en la práctica siento que se puede usar muchísimo más Con algo así, parecería que el límite llegaría rapidísimo en cuanto una conversación se alarga un poco, pero yo todavía no me he topado con eso ni una sola vez No sé si es un límite que solo aplica a Claude Code, como todavía no lo he usado mucho, no estoy seguro

  • El plan Pro cuesta $20 al mes. Hace poco habilitaron el acceso a claude code Pero he oído que algunos usuarios llegan al límite con apenas unas cuantas consultas Así que creo que esa cifra sí suena correcta Los límites de la interfaz de chat y los de Claude Code son independientes

• Está increíble, gracias por hacerlo Me pregunto si se puede instalar con uv Comparto el enlace de uv junto con un ejemplo de comandos de shell resumiendo el proceso de instalación línea por línea

  • Si ese repo tuviera una estructura de paquete con project.toml y demás, se podría instalar más rápido con pipx(pipx) así:

pipx install git+https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor ccusage_monitor uv probablemente tenga un comando similar (uvx), aunque no estoy seguro de si cumple exactamente la misma función o propósito que pipx

• Como dato, casi todo lo que se puede instalar con pip también se puede instalar con uv, así que con uv también debería ser más fácil

• Me pregunto si esta herramienta aporta algo útil aparte de ejecutarse por shell llamando a ccusage La verdad, este tipo de proyectos me decepciona un poco, y se siente como algo resuelto de una sola pasada con una herramienta de IA En el Show HN ni siquiera mencionan que todo el trabajo real lo hace otra herramienta, y eso sí decepciona

• Ayer tuve una experiencia rara con Claude Code Intenté convertir una página de tabla phtml escrita en PHP antiguo a un nuevo layout con divs, falló, y terminé gastando como 4 dólares Tal vez fue un problema de WSL, pero espero que no pase seguido

  • Claude Code tiene una curva de aprendizaje bastante marcada Hay que llevar sesiones largas de conversación, discutir bien los requisitos y guiar al modelo con preguntas claras Aun así, este tipo de fallos puede pasar de vez en cuando, así que hay que recordar que es una herramienta muy cara No es magia, por más que lo digan youtubers o bloggers