Statusline de Claude Code: configura la línea de estado del terminal para tu productividad (2026)

Autora: Jasmine, una dev que vive dentro de Claude Code cada día en Windows.

¿Qué es la statusline de Claude Code?

La statusline de Claude Code es una línea personalizable que se renderiza en la parte inferior de cada sesión de Claude Code, generada por un script de shell que tú misma configuras. Cada vez que cambia el estado de la sesión, Claude Code llama a ese script, le pasa todo el estado de la sesión como JSON por stdin e imprime lo que el script devuelve por stdout como tu línea de estado. Dicho de otro modo: recibes un bloque de JSON, eliges los campos que te importan, les das el formato que quieras, los imprimes, y Claude Code solo muestra el resultado.

Lo clave que conviene interiorizar cuanto antes: la statusline se ejecuta en local en tu máquina, no hace llamadas a la API y no cuesta tokens. No es una función de "IA": es solo un script bash/PowerShell/Python que lee el stdin. Así que puedes mostrar tanto o tan poco como quieras sin tocar la factura de tu sesión. Claude Code solo vuelve a ejecutar el script en eventos (cambio de modelo, llamada a una herramienta, actualización del contexto, etc.) y aplica un ligero debounce a las llamadas para que no se dispare constantemente, lo que significa que un script un poco más pesado no pasa nada, siempre que no abuses (mira la sección de rendimiento más abajo).

A diferencia de la barra de estado por defecto (que solo muestra tu directorio de trabajo), una statusline personalizada te permite traer exactamente lo que te importa mientras programas. Si estás empezando, lee primero qué es Claude Code y para qué sirve para tener contexto, y luego vuelve aquí para configurarla.

¿Qué deberías mostrar en la statusline para ser más productiva?

No metas todos los campos en la statusline. La buena línea es la corta, la que puedes ojear en medio segundo y aun así actuar. Después de unos meses de uso real, esto es lo que más vale la pena mostrar, en mi experiencia:

• Porcentaje de contexto restante: lo número uno. Cuando el contexto entra en la zona de peligro, puedes hacer /compact por tu cuenta o dividir el trabajo, en vez de que Claude Code te comprima la conversación a mitad de la tarea.
• Modelo activo: saber si estás en Opus o en Sonnet para no usar un mazo contra una chincheta (o al revés). Es fácil olvidar que acabas de cambiar de modelo.
• Coste de la sesión: una cifra en USD que se actualiza en vivo te da la sensación de qué tareas están quemando dinero, sobre todo cuando pagas por token de API.
• Rama de Git + recuento de archivos en stage/modificados: evita hacer commit en la rama equivocada y ve cuántos cambios sin guardar tienes.
• Límites de uso de 5 horas / 7 días (planes Pro/Max): ve cómo tu cuota se agota para que no te corten a mitad de una tarea larga.
• Directorio / worktree: práctico cuando tienes varias worktrees abiertas a la vez.

Mi regla: la línea 1 siempre lleva modelo + % de contexto, y coste/Git/límite de uso solo se añaden cuando de verdad los necesito. Para más de los comandos que uso a diario, mira la chuleta de Claude Code.

La forma más rápida: el comando /statusline

Si no quieres tocar ningún archivo de configuración, la vía más rápida es simplemente pedirlo, en lenguaje natural, dentro de tu propia sesión de Claude Code. Escribe /statusline seguido de una descripción de lo que quieres ver:

/statusline show model name and context percentage with a progress bar

Claude Code escribe el script por ti, lo guarda en ~/.claude/ y añade el bloque de configuración a settings.json automáticamente. Como este paso crea un archivo nuevo y edita tu configuración, Claude Code te pedirá que apruebes los cambios antes de escribir: solo revísalos y acéptalos. Cuando termine, la statusline aparece ya en tu siguiente interacción.

Esta es la mejor manera de conseguir un borrador rápido, que luego puedes abrir y ajustar a mano a tu gusto. Si prefieres entender primero los controles básicos y el flujo de trabajo, mira la guía de Claude Code para principiantes.

Configuración manual con settings.json (paso a paso)

¿Quieres control total? Configúrala a mano. Son solo 3 pasos.

Paso 1 - Crea el script ~/.claude/statusline.sh que lee el JSON del stdin, usa jq para extraer los campos que quieras e imprime una línea:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
printf "[%s] 📁 %s | %s%% context" "$model" "$dir" "$pct"

Paso 2 - Hazlo ejecutable:

chmod +x ~/.claude/statusline.sh

⚠️ El error más común: olvidar el chmod +x hace que la statusline no muestre nada, sin ningún error claro. Si tu línea de estado está "muda", comprueba primero el permiso de ejecución.

Paso 3 - Decláralo en ~/.claude/settings.json:

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

Claude Code lo recarga en tu siguiente interacción, sin necesidad de reiniciar. Un par de opciones útiles: padding controla el margen izquierdo (ponlo a 0 para pegarlo al borde), y refreshInterval (en milisegundos) obliga al script a volver a ejecutarse por temporizador para datos basados en tiempo, como un reloj o los límites de uso. Para un script muy corto, incluso puedes poner el comando jq -r directamente en el campo command sin un archivo aparte, pero un archivo separado es mucho más fácil de mantener.

La tabla de datos JSON: lo que recibe la statusline

En cada ejecución, el script recibe un objeto JSON completo por stdin. Aquí tienes una referencia de los campos que más usarás (fuente: la documentación oficial en code.claude.com/docs/en/statusline, consultada en 08/2026):

Nota importante: muchos campos pueden faltar o ser null, sobre todo antes de la primera respuesta de la API. Usa siempre valores por defecto en jq: // 0 para números, // "empty" o // "" para cadenas. Algunos campos más nuevos requieren una build de Claude Code lo bastante reciente; no afirmes que un campo no existe si no lo has probado en la build que estás ejecutando.

Scripts de ejemplo para copiar y pegar (elige el que necesites)

Los presets de abajo usan bash + jq. Si escribes el tuyo en Python o Node, el parseo de JSON viene integrado, así que quedan aún más cortos.

1) Barra de contexto: barra de progreso + %:

#!/bin/bash
input=$(cat)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
filled=$((pct / 10)); empty=$((10 - filled))
bar=$(printf '▓%.0s' $(seq 1 $filled))$(printf '░%.0s' $(seq 1 $empty))
printf "%s %s%%" "$bar" "$pct"

2) Git con colores: rama + archivos en stage (verde) / modificados (amarillo), usando códigos de color ANSI:

#!/bin/bash
input=$(cat)
branch=$(git branch --show-current 2>/dev/null)
staged=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
modified=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
printf " %s \033[32m+%s\033[0m \033[33m~%s\033[0m" "$branch" "$staged" "$modified"

3) Coste + duración:

#!/bin/bash
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
ms=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
sec=$((ms / 1000)); min=$((sec / 60)); s=$((sec % 60))
printf "\$%.2f | %dm %ds" "$cost" "$min" "$s"

4) Varias líneas + umbrales de color: línea 1: modelo/directorio/rama; línea 2: una barra que cambia de color (verde <70, amarillo 70-89, rojo 90+) + coste + límite de uso:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
branch=$(git branch --show-current 2>/dev/null)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
rl=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
if [ "$pct" -ge 90 ]; then c="\033[31m"; elif [ "$pct" -ge 70 ]; then c="\033[33m"; else c="\033[32m"; fi
printf "[%s] 📁 %s %s\n" "$model" "$dir" "$branch"
printf "${c}%s%% context\033[0m | \$%.2f" "$pct" "$cost"
[ -n "$rl" ] && printf " | 5h: %s%%" "$rl"

Este preset de varias líneas es el que yo uso de verdad cada día: la línea de arriba para ubicarme y la de abajo cambiando de color para avisarme cuando el contexto se está llenando; muy eficaz para que no me hagan un /compact a mitad del flujo.

Configurarla en Windows (PowerShell + Git Bash)

La mayoría de las guías por ahí son solo para bash. Si estás en Windows (como yo), hay dos caminos que funcionan.

Opción A - Git Bash: la más sencilla. Los scripts .sh de arriba se ejecutan directamente, siempre que Git Bash y jq estén instalados. Apunta command al archivo .sh como de costumbre.

Opción B - PowerShell: escribe un script .ps1 que lea el stdin y parsee el JSON:

# C:/Users/you/.claude/statusline.ps1
$data = $input | Out-String | ConvertFrom-Json
$model = $data.model.display_name
$pct = [math]::Floor($data.context_window.used_percentage)
Write-Host "[$model] $pct% context" -NoNewline

Luego decláralo en settings.json:

{
 "statusLine": {
 "type": "command",
 "command": "powershell -NoProfile -File C:/Users/you/.claude/statusline.ps1"
 }
}

⚠️ La trampa de la barra invertida en Windows: escribe siempre las rutas con barras normales (/) en el campo command. Git Bash se "come" la barra invertida \, así que el comando falla en silencio: la statusline no muestra nada y no reporta ningún error. El carácter ~ sigue funcionando bien.

Esto es justo lo que hace tropezar a mucha gente en Windows: el script es correcto, pero la ruta tiene las barras equivocadas. Cambia \ por / y funciona.

Consejo de rendimiento: no dejes que la statusline ralentice tu sesión

El script se ejecuta muy a menudo. En un repositorio grande, git status o git diff pueden tardar unos cientos de milisegundos cada vez; multiplícalo y toda la sesión se siente algo lenta. Unos cuantos consejos para mantener la statusline rápida:

• Cachea los resultados de Git en un archivo temporal indexado por session_id, actualizándolo cada ~5 segundos en vez de llamar a git en cada ejecución. Usa session_id como clave de caché; no uses $$/PID, porque cambia en cada ejecución del script y deja la caché inservible.
• Mantén la salida corta: una línea, unos pocos campos. Una línea larga es lenta y difícil de leer.
• Usa refreshInterval para datos basados en tiempo (reloj, límites de uso) en vez de recalcularlos a lo bruto.
• Lee COLUMNS/LINES para calcular el ancho y recortar cuando el terminal es estrecho.

Regla general: si el script tarda más de ~300ms, notarás el retardo. La caché y el recorte son las dos palancas más grandes.

Problemas comunes & cómo solucionarlos

Para diagnosticar, ejecuta claude --debug y fíjate en el código de salida y el stderr del script. Además, algunos emuladores (Terminal.app, por ejemplo) no admiten los enlaces OSC 8, así que, si insertas un hipervínculo en tu statusline, puede que no se pueda clicar: es una limitación del terminal, no un bug del script.

¿No quieres editar scripts? Usa un constructor visual de línea de estado

No todo el mundo quiere escribir bash o PowerShell solo para tener una línea de estado. Si es tu caso, una opción sin código es el bundle de AgentKit — ahora $149 (antes $198): su app de escritorio tiene un constructor visual de línea de estado (arrastra y suelta campos: modelo, contexto, coste, Git, etc., en vez de programar a mano) junto con un único sitio para gestionar tu licencia, skills e integraciones MCP. Para quien le tiene respeto al terminal, es una forma de montar una statusline sin tocar settings.json.

Te seré sincera: /statusline y los scripts de arriba son totalmente gratis y suficientes para casi todo el mundo; el constructor visual solo es más cómodo si quieres no-code o gestionar todo tu conjunto de skills/agents en un solo lugar. Si quieres profundizar antes de decidir, lee qué es AgentKit y si vale la pena (reseña).

Preguntas frecuentes (FAQ)

¿La statusline cuesta tokens?

No. La statusline ejecuta un script local en tu máquina y no hace llamadas a la API de Claude, así que no usa tokens. Puedes mostrar toda la información que quieras sin afectar al coste de tu sesión.

¿Funciona en Windows?

Sí. Puedes ejecutar scripts .sh a través de Git Bash, o escribir un .ps1 y llamarlo con powershell -NoProfile -File. Solo escribe tus rutas con barras normales (/) para evitar la trampa de la barra invertida.

¿Por qué no aparece mi statusline?

La causa más común es olvidar el chmod +x en el script. Otras: el script imprime en stderr en vez de stdout, no has aceptado la confianza del workspace, disableAllHooks está activado, o la ruta tiene las barras equivocadas en Windows. Ejecuta claude --debug para ver el error.

¿En qué se diferencia /statusline de editar settings.json?

El comando /statusline deja que Claude Code genere el script y lo configure por ti a partir de una descripción en lenguaje natural: rápido y estupendo para principiantes. Editar settings.json a mano te da control total sobre el contenido y el formato. Mucha gente usa /statusline para conseguir un borrador y luego ajusta el archivo a mano.

¿Para qué sirve mostrar el % de contexto?

Para gestionar la conversación de forma proactiva. Cuando el contexto está casi lleno, puedes hacer /compact o dividir el trabajo por tu cuenta en vez de que Claude Code lo comprima a mitad de la tarea, lo cual suele romper tu hilo de contexto.

¿Hay alguna configuración lista que no necesite código?

Sí. La más rápida es /statusline, que deja que Claude la escriba por ti. Si quieres una interfaz totalmente de arrastrar y soltar, sin código, el constructor visual de línea de estado de la app de escritorio de AgentKit es una opción.

Conclusión + próximos pasos

No necesitas un script elaborado. Una sola línea sencilla que muestre modelo + % de contexto ya da un impulso de productividad notable; solo súbela de nivel cuando sientas la necesidad. Empieza con /statusline, luego abre el archivo y ajústalo a tu gusto. Lee la chuleta de Claude Code para reunir los comandos que usarás a menudo, y la guía de CLAUDE.md para ayudar a Claude Code a entender mejor tu proyecto. ¿Estás empezando? Vuelve a qué es Claude Code.