Monitor de uso de Claude Code: barra de estado de límites de 5 horas y 7 días con rate_limits (script probado)

En resumen: cada vez que Claude Code actualiza la barra de estado, envía un JSON a tu script por la entrada estándar, y su campo rate_limits es el dato oficial de límites: porcentaje usado de la ventana de 5 horas y de la de 7 días, más sus horas de reinicio. Con unas 30 líneas de script lo conviertes en 5h 24% (1h23m) | 7d 41% (2d7h). El 10/11/2026 probamos el script con seis entradas simuladas y ejecutamos la herramienta de la comunidad ccusage 20.0.48 sobre datos locales para comparar qué muestra cada una. Un límite por adelantado: no tenemos una cuenta de suscripción con sesión iniciada, así que nunca vimos valores reales de rate_limits; el script se probó con datos simulados según la estructura JSON documentada.

Qué es rate_limits en la documentación oficial

Todo esto viene de la documentación oficial de la barra de estado (consultada el 10/11/2026):

Campo	Significado
rate_limits.five_hour.used_percentage / rate_limits.seven_day.used_percentage	Porcentaje usado de la ventana de 5 horas o de 7 días, de 0 a 100
rate_limits.five_hour.resets_at / rate_limits.seven_day.resets_at	Cuándo se reinicia esa ventana, segundos epoch Unix
rate_limits.spend_limit.*	Solo detrás de un gateway de Claude apps con límite de gasto; este script no lo trata

Lo que conviene saber antes (el sentido de la doc, no una cita literal):

• rate_limits solo aparece para suscriptores de claude.ai Pro, Max y Ultra (o detrás de un gateway con límite de gasto). Con API key no aparece.
• Incluso con suscripción, solo sale tras la primera respuesta de la API de la sesión, y cada ventana puede faltar por separado. El script debe tratar la ausencia.
• Cuando pasa el resets_at de una ventana, Claude Code la descarta; el script también se vuelve a ejecutar cuando una ventana llega a su hora de reinicio.
• La barra de estado se ejecuta en local y no consume tokens de la API. El script debe salir con código 0 e imprimir algo, o la barra queda en blanco.
• La barra se actualiza con un mensaje nuevo del asistente, al terminar /compact, al cambiar el modo de permisos, al alternar vim y al cambiar el command; puedes añadir refreshInterval (segundos, mínimo 1) para un temporizador.

El script (probado)

Necesita jq. Guárdalo como ~/.claude/statusline.sh:

#!/bin/bash
# Barra de estado de límites de 5 horas / 7 días (campo oficial rate_limits)
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
now=$(date +%s)

left() {  # arg: resets_at (segundos epoch) -> imprime el tiempo restante, p. ej. 1h23m
  local s=$(( $1 - now ))
  [ "$s" -le 0 ] && return
  if [ "$s" -ge 86400 ]; then printf '%dd%dh' $((s/86400)) $(((s%86400)/3600))
  else printf '%dh%02dm' $((s/3600)) $(((s%3600)/60)); fi
}
color() {  # arg: porcentaje -> color ANSI
  local p=${1%.*}
  if [ "$p" -ge 90 ]; then printf '\033[31m'
  elif [ "$p" -ge 70 ]; then printf '\033[33m'
  else printf '\033[32m'; fi
}
RESET='\033[0m'
OUT=""
for w in five_hour seven_day; do
  pct=$(echo "$input" | jq -r ".rate_limits.$w.used_percentage // empty")
  rs=$(echo "$input" | jq -r ".rate_limits.$w.resets_at // empty")
  [ -z "$pct" ] && continue
  [ "$w" = five_hour ] && label=5h || label=7d
  seg="$(color "$pct")${label} $(printf '%.0f' "$pct")%${RESET}"
  [ -n "$rs" ] && l=$(left "$rs") && [ -n "$l" ] && seg="$seg ($l)"
  OUT="${OUT:+$OUT | }$seg"
done
if [ -n "$OUT" ]; then echo -e "[$MODEL] $OUT"; else echo "[$MODEL]"; fi

Luego chmod +x ~/.claude/statusline.sh y añade esto a ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

Claude Code recarga los ajustes solo y aparece la línea. Para que la cuenta atrás avance en reposo, añade "refreshInterval": 60 (se vuelve a ejecutar cada 60 segundos). La doc también avisa de que la barra queda en blanco hasta aceptar el aviso de confianza del espacio de trabajo y de que en Windows las rutas llevan barras normales o una versión en PowerShell; mira la sección de Windows de la doc.

Umbrales de color: verde por debajo del 70 %, amarillo del 70 % al 89 %, rojo desde el 90 % (los mismos que el ejemplo oficial de varias líneas). Los porcentajes se redondean con printf '%.0f', así que 23,5 se muestra como 24 %.

Qué probamos

Construimos a mano seis entradas con la estructura JSON documentada y las pasamos al script por tubería (resets_at es la hora actual más un desplazamiento). Salida sin códigos de color:

5h 23.5%, 7d 41.2%          →  [Opus] 5h 24% (1h23m) | 7d 41% (2d7h)
5h 93%, 7d 72%              →  [Opus] 5h 93% (0h10m) | 7d 72% (1d1h)
sin rate_limits             →  [Opus]
solo seven_day, 8%          →  [Sonnet] 7d 8% (3d11h)
resets_at de 5h ya pasado   →  [Opus] 5h 50%
solo spend_limit (gateway)  →  [Opus]

También vimos los códigos de color con cat -v: 93 % rojo, 72 % amarillo, el resto verde. No probado: valores reales de rate_limits de una cuenta con suscripción, ni cómo Claude Code dibuja el script en vivo (pasamos el JSON por tubería; no montamos la barra en una sesión interactiva).

En qué se diferencia de /usage y ccusage

Método	De dónde salen los datos	Qué ves
Barra de estado + rate_limits (este artículo)	JSON que Claude Code pasa al script, campo oficial	Porcentaje usado y hora de reinicio de las ventanas de 5 horas y 7 días
Comando /usage	Comando oficial; la referencia de errores dice que muestra las ventanas de tu plan y cuándo se reinician	Las mismas ventanas del plan, pero se abre a mano
ccusage (herramienta de la comunidad)	Archivos de sesión locales; su descripción en npm es «Analyze coding (agent) CLI token usage and costs from local data»	Tokens y coste estimado por día, semana, mes y sesión
ccstatusline (herramienta de la comunidad)	Citada en los consejos de la doc oficial de la barra de estado; descripción en npm «A customizable status line formatter for Claude Code CLI»	Formato de barra de estado ya hecho; no la probamos

ccusage sí lo probamos: npx ccusage@latest --version imprimió ccusage 20.0.48. Sobre un directorio de prueba con solo sesiones simuladas, el comando daily listó por fecha los tokens de entrada, salida y caché y una columna Cost (USD), y blocks listó un «bloque de sesión» activo con tiempo transcurrido y restante más una proyección al ritmo actual. Lee los archivos de sesión de ~/.claude local, así que muestra tokens y coste estimado registrados en tu máquina, no qué porcentaje de tus ventanas de 5 horas y 7 días del servidor has gastado. El «tiempo restante» de blocks es una deducción suya a partir de registros locales; no lo comparamos con una cuenta real, así que no sabemos cuánto se aleja de la hora oficial de reinicio. La doc también dice que cost.total_cost_usd se estima en el cliente a precio de lista y puede diferir de tu factura.

Así que el reparto es: para «cuánto me falta para el límite», usa rate_limits oficial; para «cuántos tokens quemé esta semana», una herramienta local como ccusage. No mezcles los dos números. Para entender cómo funcionan los límites y en qué se diferencia Pro de Max, mira la cuota de Claude.

FAQ

No aparecen 5h y 7d

Primero: ¿eres suscriptor? Con API key rate_limits nunca aparece. Segundo: puede que la sesión aún no haya tenido su primera respuesta de la API. Luego sigue las comprobaciones de la doc: si el script es ejecutable, si imprime por stdout, si claude --debug muestra errores del script.

¿La barra de estado gasta mi cuota?

La doc dice que se ejecuta en local y no consume tokens de la API.

Quiero más campos

La doc los lista todos, por ejemplo el uso de la ventana de contexto context_window.used_percentage, el coste cost.total_cost_usd, el modelo actual y la rama de git. Edita las líneas jq del script.

Relacionado

Mejores mods de Claude Code · Dónde está settings.json · Errores de Claude Code