Tu límite de uso de Claude Code, siempre a la vista en la status line

TL;DR El JSON que recibe tu status line trae rate_limits con dos ventanas, five_hour y seven_day, cada una con used_percentage y resets_at. Léelas con jq y pinta el porcentaje en la barra. Solo aparece en suscripción (Pro, Max o Ultra), o detrás de un Claude apps gateway con límite de gasto, y tras la primera respuesta de la sesión, así que maneja la ausencia con // empty.

Actualización, 4 de noviembre de 2026: rate_limits también llega en Ultra, el antiguo Max 20x, pero con la cuenta verificada no hay ventana de 5 horas y el objeto puede faltar entero.

Actualización, 31 de octubre de 2026: rate_limits ya no es solo cosa de la suscripción: detrás de un Claude apps gateway con límite de gasto trae rate_limits.spend_limit, con su used_percentage y su resets_at, desde la v2.1.251.

Trabajas con Pro o Max. En mitad de una tarea larga, el límite de 5 horas se agota y Claude se detiene. Sin aviso previo. Existe /usage, pero tienes que parar, escribirlo y leerlo. El dato ya viene en cada respuesta de la sesión: ponlo en la status line y lo ves sin levantar la vista del código. En Ultra verificado no hay ventana de 5 horas, y rate_limits puede no llegar.

Cómo funciona

Claude Code envía a tu script de status line un JSON por stdin. Desde hace poco incluye rate_limits, con dos ventanas:

"rate_limits": {
  "five_hour":  { "used_percentage": 23.5, "resets_at": 1738425600 },
  "seven_day":  { "used_percentage": 41.2, "resets_at": 1738857600 }
}

used_percentage va de 0 a 100. resets_at es epoch en segundos (cuándo se reinicia la ventana).

Resultado, una status line real con el segmento nuevo al final:

 my-project   main │ Opus 4.8 │ ███░░ 58% │ 5h 24% · 7d 82%
                                            ╰── lo añades tú

En verde mientras vas holgado, en rojo cuando te acercas al muro.

Cómo montarlo

1. Apunta la status line a tu script

En ~/.claude/settings.json:

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

2. Lee las dos ventanas en el script

#!/usr/bin/env bash
in=$(cat)
fh=$(jq -r '.rate_limits.five_hour.used_percentage // empty' <<<"$in")
sd=$(jq -r '.rate_limits.seven_day.used_percentage // empty' <<<"$in")

# Sin ventana de 5 horas (cuenta de API o gateway) o antes de la primera respuesta: no pintes nada
[ -z "$fh" ] && exit 0

bar() {                       # $1 = porcentaje
  local p=${1%.*} c
  if   [ "$p" -ge 80 ]; then c=31   # rojo
  elif [ "$p" -ge 50 ]; then c=33   # amarillo
  else                       c=32   # verde
  fi
  printf '\033[%sm%s%%\033[0m' "$c" "$p"
}

printf '5h %s · 7d %s' "$(bar "$fh")" "$(bar "${sd:-0}")"

El script escribe una línea por stdout y esa línea es tu status line. Nada más.

3. El // empty no es opcional

rate_limits solo existe en suscripción Claude.ai (Pro, Max o Ultra), o detrás de un Claude apps gateway con límite de gasto, donde trae spend_limit, y aparece tras la primera respuesta de la sesión. Cada ventana puede faltar por separado, y en una Ultra verificada, sin franja de 5 horas, me llegó null entero. Sin el // empty y el exit 0, al arrancar verías una status line rota hasta el primer mensaje.

Referencia

Para una cuenta atrás, resta resets_at de la hora actual: jq -r '.rate_limits.five_hour.resets_at' y formatéalo con date.

Documentación oficial: Status line — rate limit usage

Esto extiende el script de status line con los campos que casi nadie usa. Cuando una de las dos barras se dispare y quieras saber qué la llenó, con el nombre de la skill o del servidor MCP, ahí está el desglose de /usage; para las cifras generales, /usage y /stats; y para entender las tres ventanas, cómo funcionan tus límites de uso. Esto es el vistazo permanente.

Y en ese mismo JSON viaja otro campo de la misma familia, prompt_cache, con el porcentaje de entrada que llega desde caché y el recuento de fallos por causa. Es la versión de barra permanente de la línea que te dice qué te rompió la caché, y el segmento ya está escrito: la barra se repinta sola cuando la caché se enfría.

Requisitos

• Claude Code v2.1.x, jq, y plan con suscripción (Pro, Max o Ultra). En cuenta de API no hay rate_limits. Detrás de un Claude apps gateway con límite de gasto llega rate_limits.spend_limit, que necesita la v2.1.251. El campo prompt_cache necesita la v2.1.251 y no depende del plan.