Claude Code status line: coste, contexto y rama a la vista

Q: ¿El coste de la status line es lo que pago?

No necesariamente. cost.total_cost_usd es una estimación a precio de lista y la documentación avisa de que puede diferir de tu factura. Con Pro o Max te sirve más rate_limits.

Llevas una hora con Claude Code. La tarea iba bien. De pronto el agente propone algo que ya descartaste hace veinte minutos, y no sabes si es mala suerte o si el contexto está al límite.

Tecleas /context. Luego /usage. Luego git branch, porque tampoco recuerdas si estabas en la rama buena. Tres comandos para saber algo que debería estar delante de ti todo el rato.

Para eso existe la Claude Code status line: una línea al pie de la terminal que tú decides qué muestra.

En corto: la status line de Claude Code es un comando que defines en settings.json bajo la clave statusLine. Claude Code le pasa un JSON por stdin con el modelo, el coste estimado, el directorio y el uso de contexto, y pinta lo que tu script imprime. Con unas 30 líneas de bash y jq tienes modelo, rama, coste y contexto siempre a la vista.

¿Qué es la Claude Code status line?

La status line es una barra configurable en la parte inferior de Claude Code que ejecuta un script tuyo, le pasa datos de la sesión en JSON por stdin y muestra lo que el script escribe en stdout.

Según la documentación oficial (consultada en octubre de 2026), se ejecuta en local y no consume tokens de la API. Admite varias líneas, colores ANSI y enlaces clicables.

Es otra forma de personalizar Claude Code, distinta de los mods que protegen tus tests: un mod cambia lo que el agente puede hacer; la status line, lo que tú ves.

Cómo se configura la Claude Code status line en settings.json

Se configura con un objeto statusLine de tipo command en ~/.claude/settings.json o en los settings del proyecto. El campo command apunta a un script o a un comando de shell en línea:

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

Admite tres campos opcionales: padding añade espacio horizontal, refreshInterval vuelve a ejecutar el comando cada N segundos (mínimo 1) y hideVimModeIndicator oculta el -- INSERT -- si ya pintas tú el modo vim.

Si no quieres escribir nada, /statusline genera el script a partir de una descripción en lenguaje natural.

El script no corre en bucle: se ejecuta al empezar la sesión y después con eventos, como un mensaje nuevo del asistente o el final de /compact. Claude Code agrupa los cambios con un debounce de 300 ms y cancela el script en curso si llega otra actualización.

Qué datos recibe tu script por stdin

Tu script recibe un JSON con más de 30 campos documentados. Estos son los que usa este post y un par que conviene conocer:

Campo	Qué contiene	Para qué lo usas
`model.display_name`	Nombre visible del modelo	Saber si estás en Opus o en Sonnet
`workspace.current_dir`	Directorio de trabajo actual (igual que `cwd`)	Ejecutar `git` en el sitio correcto
`cost.total_cost_usd`	Coste estimado de la sesión en USD, a precio de lista. Vuelve a $0 tras `/clear` desde la v2.1.211	Ver cuánto llevas gastado
`context_window.used_percentage`	Porcentaje de contexto usado, ya calculado	Decidir cuándo compactar o empezar de cero
`context_window.context_window_size`	200.000 tokens por defecto, 1.000.000 en modelos con contexto extendido	Interpretar el porcentaje
`session_id`	Identificador único de la sesión	Nombrar ficheros de caché sin colisiones
`rate_limits.five_hour.used_percentage`	Uso de la ventana de 5 horas (solo Pro y Max, y a partir de la primera respuesta de la API)	Vigilar el límite de la suscripción

Dos detalles te ahorran bugs. used_percentage puede llegar a null al principio de la sesión, y se calcula solo con tokens de entrada (input_tokens + cache_creation_input_tokens + cache_read_input_tokens). Por eso el script usa // 0 como valor por defecto.

Script completo: modelo, rama, coste y contexto

Una sola llamada a jq, la rama con git -C, el coste con dos decimales y el contexto en verde, amarillo o rojo según se llena:

#!/usr/bin/env bash
# statusline.sh: modelo | rama | coste | contexto
input=$(cat)

# Una sola llamada a jq: cuatro valores separados por tabulador.
# tr quita el \r que añade jq.exe en Windows; en macOS y Linux no hace nada.
IFS=$&#39;\t&#39; read -r MODEL DIR COST PCT < <(
  echo "$input" | jq -r &#39;[
    ((.model.display_name | select(. != "")) // "?"),
    ((.workspace.current_dir | select(. != "")) // .cwd // "."),
    (.cost.total_cost_usd // 0),
    (.context_window.used_percentage // 0 | floor)
  ] | @tsv&#39; | tr -d &#39;\r&#39;
)

# Rama de git (o commit corto si HEAD está desacoplado)
if git -C "$DIR" rev-parse --git-dir >/dev/null 2>&1; then
  BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
  [ -z "$BRANCH" ] && BRANCH="detached@$(git -C "$DIR" rev-parse --short HEAD 2>/dev/null)"
else
  BRANCH="sin git"
fi

# LC_ALL=C evita que un locale con coma decimal cambie el formato
COST_FMT=$(LC_ALL=C printf &#39;$%.2f&#39; "$COST")

# Verde por debajo del 50 %, amarillo hasta el 80 %, rojo a partir de ahí
if [ "$PCT" -ge 80 ]; then COLOR=&#39;\033[31m&#39;
elif [ "$PCT" -ge 50 ]; then COLOR=&#39;\033[33m&#39;
else COLOR=&#39;\033[32m&#39;
fi
RESET=&#39;\033[0m&#39;

printf &#39;%s | %s | %s | %bctx %s%%%b\n&#39; "$MODEL" "$BRANCH" "$COST_FMT" "$COLOR" "$PCT" "$RESET"

Necesitas jq instalado (brew install jq, apt install jq o winget install jqlang.jq). Guárdalo en ~/.claude/statusline.sh, dale permisos con chmod +x y añade el bloque de settings.json de arriba. Antes, pruébalo a mano desde un repo, como recomienda la documentación:

echo &#39;{"model":{"display_name":"Opus"},"workspace":{"current_dir":"."},"cost":{"total_cost_usd":4.5},"context_window":{"used_percentage":83.6}}&#39; | ~/.claude/statusline.sh

En la rama feat/statusline imprime Opus | feat/statusline | $4.50 | ctx 83%, con el porcentaje en rojo. Tres decisiones del script no son obvias.

Un solo jq. Cuatro llamadas a jq son cuatro procesos por cada mensaje del asistente. Con @tsv sacas todo de una vez.

LC_ALL=C en el printf. Con un locale como es_ES.UTF-8, el printf de bash espera coma decimal: 0.5 le parece un número inválido y pinta 0,00. Es un fallo silencioso que aparece en cualquier locale con coma decimal: es_ES, de_DE, fr_FR, pt_BR…

tr -d '\r'. En Windows, jq.exe termina la salida en CRLF. Sin el tr, el porcentaje llega como 8\r y la comparación -ge falla. Claude Code usa Git Bash en Windows si lo tienes instalado; escribe las rutas del command con barras normales (C:/Users/...), porque las invertidas se pierden sin error visible.

Por qué la Claude Code status line cambia cómo trabajas

Ver el coste y el contexto en todo momento convierte dos decisiones que tomabas tarde en decisiones que tomas a tiempo: cuándo cortar la sesión y qué modelo usar.

Con el contexto se ve más claro. Cuando el porcentaje se pone amarillo, decides tú: compactas, abres una sesión nueva con un resumen o recortas lo que el agente lee. Si no lo ves, decide el compactado automático. En un monorepo, darle solo la rebanada de código que necesita hace que ese número suba despacio.

El coste funciona igual. Un número que crece mientras miras te obliga a preguntarte si esa tarea necesitaba Opus. Si delegas en subagentes, entiende por qué el coste sube al cambiar de modelo antes de culpar al agente.

Y la rama: que el agente haga commits en main porque olvidaste cambiar de rama no es un fallo del modelo. Es información que no tenías delante.

Esta disciplina de sesión (contexto acotado, una tarea por sesión, coste vigilado) es la base del flujo de Construye con IA: de la idea al producto con Claude Code.

Límites de la status line: lo que no te cuenta

La Claude Code status line te da señales, no la verdad contable. Ten claros estos cinco límites:

Límite	Por qué pasa	Qué hacer
El coste es una estimación	Se calcula en el cliente a precio de lista y puede no coincidir con tu factura	Usa la consola de facturación para cuentas reales
Con suscripción, el coste no es lo que pagas	En Pro y Max el uso va incluido en la cuota; solo los usage credits se cobran aparte	Mira `rate_limits` en lugar de `cost`
Un script lento congela la línea	La salida solo se pinta cuando el script termina	Nada de llamadas de red; cachea `git status` por `session_id`
Un fallo la deja en blanco	Código de salida distinto de 0 o salida vacía	Prueba siempre con un JSON de ejemplo
Pierdes los atajos del pie	Con una status line propia, Claude Code deja de mostrar casi todas las pistas de teclado, como `esc to interrupt`	Apréndete los atajos antes de quitarlos de la vista

La discrepancia de coste no es teórica. En el issue #33887 de anthropics/claude-code, un usuario reportó que la status line mostraba bastante menos que /cost, que marcaba 92,58 dólares en la misma sesión. Se cerró por inactividad sin respuesta de mantenedores.

Con el contexto pasó algo parecido. En el issue #15455, la línea seguía marcando un 72 % tras /compact mientras /context decía 45 %. La documentación actual indica que current_usage vuelve a null tras /compact hasta la siguiente llamada a la API: tu script debe aguantar valores vacíos.

Sobre la velocidad: con el JSON de ejemplo, en Git Bash sobre Windows, este script tarda unos 175 ms por ejecución. Es aceptable porque solo corre en eventos. Si añades git status en un repo grande, usa la caché por session_id que propone la documentación.

Cómo empezar hoy con tu status line

Copia el script, pruébalo con el echo y añade el bloque de tu Claude Code status line a ~/.claude/settings.json. Son cinco minutos. Desde ese momento, cuando el contexto se ponga amarillo, cortar la sesión será decisión tuya y no del compactado automático.

Si quieres llevar ese control más allá de la terminal, con especificaciones y revisión del código que genera el agente, es lo que trabajamos en el workshop SDD + Agentic Engineering.

Preguntas frecuentes

¿La status line de Claude Code consume tokens?

No. Según la documentación oficial, el script se ejecuta en local y no consume tokens de la API. Claude Code solo le pasa el JSON de la sesión por stdin.

¿Cada cuánto se actualiza la status line?

Al empezar la sesión y después con eventos: un mensaje nuevo del asistente, el final de /compact o un cambio de modo de permisos, entre otros. Para datos que cambian con el tiempo, añade refreshInterval en segundos.

¿Funciona la status line en Windows?

Sí. Claude Code ejecuta el comando con Git Bash si está instalado y, si no, con PowerShell; este script de bash necesita Git Bash. Usa barras normales en las rutas y elimina el \r que añade jq.exe.

¿El coste de la status line es lo que pago?

No necesariamente. cost.total_cost_usd es una estimación a precio de lista y la documentación avisa de que puede diferir de tu factura. Con Pro o Max te sirve más rate_limits.

¿Por qué mi status line aparece en blanco?

Suele ser un script que termina con un código distinto de 0, que no imprime nada o un directorio en el que aún no aceptaste el diálogo de confianza. Pruébalo a mano con un JSON de ejemplo. Si sigue en blanco, arranca con claude --debug: registra el stderr del script en cada ejecución y te dice si se saltó por no haber aceptado la confianza del directorio.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.