Receta · Básico · 10 min

Statusline de Claude Code: modelo, contexto y límites en vivo

Q: ¿Por qué no veo el uso de 5 h y 7 días?

El objeto rate_limits solo llega a suscriptores Pro, Max y Ultra (o detrás de un gateway con límite de gasto) y solo después de la primera respuesta de la sesión. Con una clave de API no aparece. Cada ventana puede faltar por separado.

Q: ¿El coste que muestra es lo que pago?

No necesariamente. cost.total_cost_usd es una estimación a precio de lista calculada en tu equipo; la doc avisa de que puede diferir de la factura real y en suscripciones no es lo que te cobran. Vuelve a 0 con /clear.

Q: Sale «--» o valores vacíos, ¿está roto?

Al principio de la sesión algunos campos llegan como null. Usa valores por defecto (en Python or 0, en jq // 0). Si siguen vacíos tras varios mensajes, reinicia Claude Code.

Q: ¿La pongo en el proyecto o en mi usuario?

En ~/.claude/settings.json si es tuya. En .claude/settings.json del proyecto la hereda el equipo, y solo se ejecuta cuando cada persona acepta la confianza en la carpeta. Para saber qué otras piezas se configuran ahí, mira qué pieza usar.

Una barra de estado para Claude Code en Python sin dependencias: modelo, rama, contexto con color, límites de 5 h y 7 días y qué hacer si no aparece.

Portada: Statusline de Claude Code: modelo, contexto y límites en vivo

Probado con Claude Code 2.1.316 · revisado 2026-11-01

Ver los archivos en GitHub Gratis · licencia MIT

El problema

Mientras trabajas con Claude Code no sabes cuánto contexto te queda, en qué rama estás ni cuánto llevas gastado de tus límites de 5 horas y 7 días hasta que es tarde. La statusline lo resuelve: una fila al pie que ejecuta tu script. Pero muchos scripts de ejemplo usan jq, que no viene instalado en Ubuntu (lo comprobamos), y entonces la barra sale vacía sin que sepas por qué.

La solución

La barra de estado (status line) es una fila personalizable al pie de Claude Code, encima de los indicadores del pie. Claude Code ejecuta el comando que configures, le pasa por la entrada estándar un JSON con datos de la sesión (modelo, carpeta, contexto, coste estimado y, en planes Pro, Max y Ultra, el uso de los límites de 5 horas y 7 días) y muestra lo que el script imprima por la salida estándar. Se ejecuta en local y no gasta tokens.

1. La vía rápida: /statusline

Si no quieres escribir nada, usa el comando /statusline con lo que quieres ver en lenguaje natural:

/statusline muestra el modelo, la rama de git y el porcentaje de contexto con una barra de progreso

Claude Code genera un script en ~/.claude/ y actualiza tu configuración; aprueba las ediciones si te pregunta. Sin argumentos, intenta configurarla a partir del prompt de tu shell. Para quitarla, /statusline delete (o «clear», «remove it»), o borra a mano la clave statusLine de tu settings.json.

La vía rápida está bien para empezar, pero conviene saber qué hay dentro: si el script generado usa jq y no lo tienes instalado, la barra sale vacía o con basura. Por eso esta receta usa Python, que viene en casi cualquier Linux y macOS. Si prefieres jq, instálalo antes (sudo apt install jq en Ubuntu o Debian).

2. El script (Python, sin dependencias)

Guárdalo como ~/.claude/statusline.py:

#!/usr/bin/env python3
# Guárdalo como ~/.claude/statusline.py y dale permisos: chmod +x ~/.claude/statusline.py
"""Barra de estado: modelo · carpeta (rama) · contexto · límites 5 h / 7 d · coste."""
import json, os, subprocess, sys

d = json.load(sys.stdin)
model = (d.get("model") or {}).get("display_name", "?")
cwd = (d.get("workspace") or {}).get("current_dir") or d.get("cwd", "")
pct = int((d.get("context_window") or {}).get("used_percentage") or 0)
cost = (d.get("cost") or {}).get("total_cost_usd") or 0
limits = d.get("rate_limits") or {}

try:
    branch = subprocess.run(["git", "-C", cwd, "branch", "--show-current"],
                            capture_output=True, text=True, timeout=1).stdout.strip()
except Exception:
    branch = ""

color = "\033[31m" if pct >= 80 else "\033[33m" if pct >= 50 else "\033[32m"
parts = [f"[{model}] {os.path.basename(cwd)}" + (f" ({branch})" if branch else ""),
         f"{color}ctx {pct}%\033[0m"]
for key, label in (("five_hour", "5h"), ("seven_day", "7d")):
    used = (limits.get(key) or {}).get("used_percentage")
    if used is not None:
        parts.append(f"{label} {used:.0f}%")
parts.append(f"${cost:.2f}")
print(" | ".join(parts))

Muestra el modelo entre corchetes, la carpeta y la rama de git, el porcentaje de contexto con color (verde por debajo del 50 %, amarillo hasta el 80 %, rojo desde el 80 %), el uso de los límites de 5 h y 7 días si existen y el coste estimado de la sesión. Usa los campos oficiales:

Campo	Qué es
`model.display_name`	Nombre del modelo
`workspace.current_dir`	Carpeta de trabajo
`context_window.used_percentage`	Porcentaje de contexto usado
`rate_limits.five_hour.used_percentage`	Uso del límite de 5 horas
`rate_limits.seven_day.used_percentage`	Uso del límite de 7 días
`cost.total_cost_usd`	Coste estimado de la sesión

Dos detalles importantes de la doc: rate_limits solo existe para suscriptores Pro, Max y Ultra (o detrás de un gateway con límite de gasto) y solo tras la primera respuesta de la sesión; y used_percentage puede venir null al principio. Por eso el script usa valores por defecto y nunca falla si falta un campo. El coste es una estimación a precio de lista calculada en tu equipo: puede no coincidir con tu factura y vuelve a 0 con /clear.

3. Actívalo en settings.json

Dale permisos al script y añade el bloque statusLine a ~/.claude/settings.json:

chmod +x ~/.claude/statusline.py

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

También vale en la configuración del proyecto, pero entonces lo hereda todo el equipo. Claude Code recarga la configuración solo y ejecuta el script al guardar. Si cambias el script, el cambio se ve en el siguiente evento que lo vuelva a ejecutar (por ejemplo, el siguiente mensaje). Para datos que cambian con el tiempo, como un reloj, añade "refreshInterval": 5 dentro de statusLine y se ejecutará también cada 5 segundos (mínimo 1).

Si prefieres jq, esta es la alternativa de una línea de la doc oficial (requiere jq instalado):

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

4. Extras que valen la pena

Varias líneas: cada línea que imprimas es una fila.
Colores y enlaces: colores ANSI (\033[32m es verde) y enlaces pulsables OSC 8 en terminales que los soportan.
Ancho: dentro del script tput cols no funciona porque Claude Code captura la salida; usa las variables COLUMNS y LINES, que Claude Code define antes de ejecutarlo.
Caché del prompt: el objeto prompt_cache trae warm (si la caché sigue viva) y hit_ratio; mostrar «cache fría» te avisa de que el siguiente mensaje será más caro.
Operaciones lentas: si muestras git status en un repo grande, guarda el resultado unos segundos en un archivo temporal con el session_id en el nombre (no uses $$, cambia en cada ejecución).
Subagentes: subagentStatusLine permite personalizar la fila de cada subagente en el panel de agentes.
Algo ya hecho: la doc cita proyectos de la comunidad como ccstatusline y starship-claude.

Compruébalo

Antes de mirar la barra, prueba el script fuera de Claude Code con datos simulados. Si imprime una línea y termina con código 0, en Claude Code funcionará. Prueba también un JSON casi vacío para comprobar que aguanta los campos ausentes o null:

# 1. Prueba el script fuera de Claude Code con datos simulados
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"'$PWD'"},"context_window":{"used_percentage":62.4},"cost":{"total_cost_usd":0.43},"rate_limits":{"five_hour":{"used_percentage":23.5},"seven_day":{"used_percentage":41.2}},"session_id":"prueba"}' | ~/.claude/statusline.py
# [Opus] mi-proyecto (main) | ctx 62% | 5h 24% | 7d 41% | $0.43

# 2. Sin límites ni datos (inicio de sesión o clave de API): no debe romperse
echo '{"model":{"display_name":"Sonnet"},"workspace":{"current_dir":"/tmp"},"context_window":{"used_percentage":null},"session_id":"x"}' | ~/.claude/statusline.py; echo "exit=$?"
# [Sonnet] tmp | ctx 0% | $0.00
# exit=0

Lo probamos el 1-nov-2026 en Linux con Claude Code 2.1.316 y Python 3.12.3, sin tocar la configuración del usuario (con claude --settings <archivo>): el script pasa las dos pruebas y, en una carpeta de confianza, la barra se pintó así:

[Opus 5.5] proyecto-50usd (main) | ctx 0% | $0.00

No llegamos a ver rate_limits en la barra real, porque solo llega tras la primera respuesta y en esa prueba no enviamos ningún mensaje.

Por qué funciona

El script corre al empezar o reanudar una sesión y otra vez cuando llega un mensaje nuevo del asistente, cuando termina /compact, cuando cambias de modo de permisos o de modo vim, cuando cambias el comando y cuando una ventana de límite llega a su hora de reinicio. Las actualizaciones se agrupan con una espera de 300 ms y, si llega otra mientras tu script sigue corriendo, el anterior se cancela. Ojo: con una barra propia, Claude Code deja de mostrar la mayoría de las pistas de teclado del pie, como «esc to interrupt», y la barra se oculta un momento durante algunos diálogos, por ejemplo al pedirte permiso.

¿Por qué /context marca más que tu barra? No es un error. La barra muestra los recuentos de la última respuesta de la API, mientras que /context añade una estimación de los mensajes que llegaron después, así que /context puede marcar más hasta la siguiente respuesta. context_window.used_percentage se calcula solo con tokens de entrada (entrada normal más escritura y lectura de caché), sin contar la salida; si calculas el porcentaje tú mismo desde current_usage, usa la misma fórmula, y ten en cuenta que current_usage vale null antes de la primera llamada y justo después de /compact. Otro campo útil: exceeds_200k_tokens indica si la última respuesta pasó de 200 000 tokens, un umbral fijo aunque tu modelo tenga una ventana de 1 millón; context_window.context_window_size te da el tamaño real de la ventana. Todo está en la documentación de la statusline.

Errores típicos

Si tu statusline no aparece, revisa en este orden:

Barra en blanco en una carpeta nueva → no aceptaste la confianza en la carpeta: como la barra ejecuta un comando de shell, sigue la misma regla que los hooks y queda en blanco hasta que aceptes el diálogo «Is this a project you created or one you trust?» para esa carpeta (o una superior) → reinicia Claude Code y acepta el diálogo.
No sale nada → el script no tiene permisos de ejecución → chmod +x ~/.claude/statusline.py.
Imprime pero no se ve → escribe por stderr → la barra solo muestra lo que sale por stdout.
Barra vacía tras un error → el script terminó con un código distinto de 0 o no imprimió nada → pruébalo con los datos simulados de «Compruébalo».
El registro dice jq: not found → el comando usa jq y no está instalado (nos pasó en este PC) → instálalo o usa el script de Python.
Desapareció sin aviso → disableAllHooks: true fuera de la configuración gestionada desactiva la barra, y allowManagedHooksOnly de tu organización la hace desaparecer → revisa tus settings.
No funciona en Windows con Git Bash → la ruta del comando lleva barras \ → usa barras /.

Para ver qué pasa, arranca con registro de depuración. Registra el stderr de tu script y su código de salida:

# ¿Sigue en blanco? Arranca con registro de depuración y busca la barra
claude --debug-file /tmp/claude-debug.log
# (en otra terminal)
grep -i "statusline\|status line" /tmp/claude-debug.log

Estas líneas las vimos en nuestras pruebas, la primera con el script de Python y las otras dos con un comando que usaba jq sin tenerlo instalado:

[DEBUG] StatusLine [~/.claude/statusline.py] completed with status 0
[DEBUG] StatusLine [jq -r ...] stderr: /bin/sh: 1: jq: not found
[WARN] StatusLine [jq -r ...] completed with status 1

Si el problema es la confianza en la carpeta, según la doc oficial el registro dice Status line command skipped: workspace trust not accepted. Ese mensaje no lo comprobamos nosotros: no aceptamos el diálogo de confianza para no modificar la configuración del usuario.

Preguntas frecuentes

¿La statusline gasta tokens o límite de uso?

No. Se ejecuta en tu equipo con datos que Claude Code ya tiene; no hace llamadas a la API.

¿Por qué no veo el uso de 5 h y 7 días?

El objeto rate_limits solo llega a suscriptores Pro, Max y Ultra (o detrás de un gateway con límite de gasto) y solo después de la primera respuesta de la sesión. Con una clave de API no aparece. Cada ventana puede faltar por separado.

¿El coste que muestra es lo que pago?

No necesariamente. cost.total_cost_usd es una estimación a precio de lista calculada en tu equipo; la doc avisa de que puede diferir de la factura real y en suscripciones no es lo que te cobran. Vuelve a 0 con /clear.

Sale «--» o valores vacíos, ¿está roto?

Al principio de la sesión algunos campos llegan como null. Usa valores por defecto (en Python or 0, en jq // 0). Si siguen vacíos tras varios mensajes, reinicia Claude Code.

¿Funciona en Windows?

Sí. Claude Code ejecuta el comando con Git Bash si está instalado o con PowerShell si no. Escribe las rutas con barras /, o invoca un script con powershell -NoProfile -File C:/Users/tu-usuario/.claude/statusline.ps1.

¿La pongo en el proyecto o en mi usuario?

En ~/.claude/settings.json si es tuya. En .claude/settings.json del proyecto la hereda el equipo, y solo se ejecuta cuando cada persona acepta la confianza en la carpeta. Para saber qué otras piezas se configuran ahí, mira qué pieza usar.

Toda la biblioteca