Una de las features que la gente subestima cuando aprende Claude Code es la statusline: la barra que aparece en la parte inferior del terminal mostrando información de la sesión activa. Bien configurada, ahorra contexto mental: ves qué modelo está activo, cuántos tokens llevas, qué branch tocas y si estás en un worktree, todo sin salir del flujo.
Si vienes del pillar técnico de cómo funciona Claude Code por dentro, este post completa el rincón de la UX. Vamos a ver cómo se configura la statusline, qué información puedes mostrar, ejemplos reales y los principales trucos de productividad que la comunidad ha ido publicando.
Qué es la statusline de Claude Code
La statusline es una barra inferior persistente que Claude Code renderiza en el terminal mientras trabajas. A diferencia del prompt de bash/zsh, está dentro de la sesión de Claude y se actualiza con eventos del agente: nuevo mensaje, cambio de permisos, toggle de vim mode.
Por defecto sale vacía. Con /statusline (o editando la config a mano) le dices que muestre lo que necesites: modelo activo, branch git, tokens consumidos, hora, lo que sea.
Configuración básica
La statusline se configura en settings.json (en ~/.claude/ para configuración global o en .claude/settings.json del proyecto). El bloque mínimo:
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}Tres campos:
type: hoy"command". Claude Code ejecuta un comando externo y muestra su stdout.command: ruta a un script ejecutable o comando inline. Funciona cualquier shell que devuelva texto por stdout.padding: caracteres en blanco a izquierda y derecha (estético).
Cuando Claude Code arranca, ejecuta tu script y le pasa por stdin un JSON con datos de sesión. Tu script lee ese JSON, decide qué mostrar, lo imprime por stdout y Claude Code lo pinta. Tan simple como eso.
El JSON que Claude Code te pasa por stdin
Esta es la parte interesante: Claude Code te entrega un objeto con metadatos de la sesión. La estructura aproximada:
{
"session_id": "abc123...",
"model": "claude-opus-4-7",
"permission_mode": "default",
"cwd": "/Users/saulgomezjimenez/proyectos/levante",
"vim_mode": false,
"tokens": {
"input": 12340,
"output": 4520,
"cache_read": 8200,
"cache_creation": 4140
},
"rate_limit": {
"requests_remaining": 49,
"tokens_remaining": 192000
}
}(Los nombres exactos pueden variar entre versiones; consulta la doc oficial de statusline para tu versión).
Tu script lee esto desde stdin y produce una línea de texto. Eso es todo lo que tienes que entender.
Generar la statusline con /statusline
La forma más rápida de empezar: dentro de una sesión de Claude Code, escribes:
/statusline mostrar modelo, branch git y tokens consumidos en esta sesiónClaude Code genera un script en ~/.claude/statusline.sh, actualiza tu settings.json, y queda listo. Si el resultado no te gusta, ejecutas /statusline con otra descripción y lo regenera.
Es la forma "bonita" de empezar. La forma profesional es escribir el script tú mismo para tener control real.
Ejemplo 1: bash mínimo
#!/usr/bin/env bash
# ~/.claude/statusline.sh
INPUT=$(cat)
MODEL=$(echo "$INPUT" | jq -r '.model // "?"')
CWD=$(echo "$INPUT" | jq -r '.cwd // "?"')
BRANCH=$(cd "$CWD" 2>/dev/null && git branch --show-current 2>/dev/null || echo "-")
printf "🤖 %s | 📁 %s | 🌿 %s" "$MODEL" "$(basename "$CWD")" "$BRANCH"Hazlo ejecutable (chmod +x ~/.claude/statusline.sh) y reinicia Claude Code. La barra muestra modelo, directorio actual y branch git.
El usuario emoji-shy: cambia los iconos por texto plano. Aquí solo lo uso para ilustrar separación visual.
Ejemplo 2: Python con tokens y rate limit
Para algo más rico, Python permite parsing limpio:
#!/usr/bin/env python3
import json
import sys
import subprocess
from pathlib import Path
data = json.load(sys.stdin)
model = data.get("model", "?").replace("claude-", "")
cwd = data.get("cwd", "")
tokens = data.get("tokens", {})
input_t = tokens.get("input", 0)
output_t = tokens.get("output", 0)
cache_r = tokens.get("cache_read", 0)
# Branch git si lo hay
try:
branch = subprocess.check_output(
["git", "branch", "--show-current"],
cwd=cwd, stderr=subprocess.DEVNULL, text=True
).strip() or "-"
except Exception:
branch = "-"
# Worktree (si .git es archivo, estamos en worktree)
worktree = ""
if Path(cwd, ".git").is_file():
worktree = " [worktree]"
total = input_t + output_t
print(f"{model} | {Path(cwd).name}{worktree} | {branch} | "
f"in:{input_t/1000:.1f}k out:{output_t/1000:.1f}k cache:{cache_r/1000:.1f}k "
f"tot:{total/1000:.1f}k")Apuntas command a este script y verás la información en cada actualización.
Ejemplo 3: alertas de rate limit
Una de las cosas más valiosas: avisar cuando te acercas al rate limit para no quedarte tirado en mitad de una sesión larga. El bloque relevante:
rate = data.get("rate_limit", {})
tokens_remaining = rate.get("tokens_remaining", float("inf"))
if tokens_remaining < 50_000:
rate_str = f"⚠️ rate:{tokens_remaining/1000:.0f}k"
elif tokens_remaining < 200_000:
rate_str = f"rate:{tokens_remaining/1000:.0f}k"
else:
rate_str = ""Cuando bajas de 50K tokens disponibles aparece el aviso; arriba se queda silencioso para no añadir ruido visual.
Ejemplo 4: integración con worktree y multi-sesión
Si trabajas con worktrees y subagentes, te interesa que la statusline diga qué worktree exactamente estás usando:
import subprocess
try:
wt_path = subprocess.check_output(
["git", "rev-parse", "--show-toplevel"],
cwd=cwd, stderr=subprocess.DEVNULL, text=True
).strip()
wt_name = Path(wt_path).name
except Exception:
wt_name = "?"
# Sesion ID corto para distinguir paralelas
session_id = data.get("session_id", "?")[:6]
print(f"[{session_id}] {model} | {wt_name} | {branch} ...")Cuando lanzas tres sesiones en paralelo sobre el mismo repo, los IDs distintos te ayudan a no confundir terminales.
Ejemplo 5: integrar con ccstatusline o tools de comunidad
La comunidad ha publicado statuslines listas que merece la pena conocer:
ccstatusline: statusline configurable con powerline, themes, métricas extendidas. Si te gustan los prompts elaborados estilo Oh My Zsh, este es tu starting point.ClaudeCodeStatusLinede Daniel Tonon: muestra modelo, tokens, rate limits y git en tiempo real, con código limpio.claude-statuslinede Felipe Elias: configurable con presets y diseño minimalista.
Instalación típica:
npm i -g ccstatusline
ccstatusline initY editas el ~/.claude/settings.json apuntando al script generado.
Cuándo se ejecuta tu script
Para hacer un script eficiente conviene saber el ciclo:
Después de cada nuevo mensaje del asistente.
Cuando el permission mode cambia (default → bypassPermissions, etc.).
Cuando vim mode togglea.
Debounce de 300ms: cambios rápidos se agrupan y tu script se ejecuta una sola vez tras estabilizarse.
Esto significa que tu script debe ser rápido: idealmente menos de 50 ms de wall time. Si ejecutas comandos lentos (network, scripts de Python pesados), la UX se nota. Soluciones:
Cachea: si ya calculaste el branch hace un segundo, no lo recalcules.
Background: si necesitas algo lento (status remote, GitHub API), córrelo aparte y lee de un cache.
Bash > Python > Node: bash arranca más rápido que un intérprete pesado.
Confianza y seguridad
La statusline ejecuta un comando shell cada actualización. Por eso requiere haber aceptado el workspace trust del directorio actual, igual que hooks o cualquier otro shell-execution feature de Claude Code. Esto es importante:
No copies y pegues scripts de la red sin leerlos. Cualquier script que pongas tiene control de tu shell.
Para entornos compartidos, prefiere scripts en
~/.claude/(tu home) en lugar de.claude/del repo (cualquiera con commit access podría modificarlos).Si te interesa el modelo de seguridad de Claude Code en profundidad, tienes el detalle en cómo Claude Code decide si ejecutar un comando.
Casos de uso reales
Coste por sesión: si trabajas con BYOK pagado por tokens, la statusline te dice en directo cuánto llevas gastado. Multiplica
tokens.inputytokens.outputpor el precio por million de tu modelo y muestra$0.42.Trabajo en paralelo: con tareas en background o múltiples sesiones, mostrar
session_idcorto evita confundir terminales.Permisos visibles: pintar
permission_modecon un color cuando estás enbypassPermissionsayuda a no ejecutarrm -rfsin querer.Tiempo de sesión: añade un timestamp de cuándo arrancaste para saber cuánto llevas tecleando. Al cabo de la cuarta hora ya empiezas a equivocarte.
Detección de modelo bajo: si caes a Sonnet automáticamente por límite, la statusline lo nota y te avisa antes de que te sorprenda.
Statusline + hooks: combinación potente
La statusline pinta información. Los hooks de Claude Code ejecutan acciones en eventos. Combinarlos da workflows potentes:
Hook
OnUserPromptSubmitque loguea cada prompt en~/.claude/log.jsonl+ statusline que cuenta cuántos prompts llevas.Hook
OnToolUseque registra coste por tool + statusline que muestra el agregado.Hook
OnSubagentStopque cuenta subagentes lanzados + statusline que los muestra.
La statusline es la vista del state interno; los hooks son los write sobre ese state. Juntos te dan observabilidad real del agente.
Errores comunes
Script no es ejecutable: olvidar el
chmod +x. Claude Code lanza el comando y falla silenciosamente.Script en directorio no fiable: si pones el script en un repo nuevo y no has aceptado el trust, no se ejecuta.
Script lento: el debounce de 300ms enmascara el problema, pero notas que la barra "se queda atrás" tras cada mensaje.
stdout vs stderr: solo stdout pinta. Los
printa stderr no se ven, pero pueden ensuciar logs.JSON parsing roto: si el script falla al parsear stdin, la statusline queda en blanco sin error visible. Mete try/except y log a archivo para depurar.
Conclusión
La statusline es opcional pero gratis: 30 minutos de configuración te dan información persistente que reduce contexto mental durante semanas. Empieza con /statusline para que Claude te genere la primera versión, y cuando tengas claro qué quieres mostrar, escribe el script a mano para tener control.
Si compartes equipo, considera versionar la statusline en .claude/settings.json del repo (con su script asociado) para que todos vean la misma información. Combina con hooks para observabilidad completa, y con Claude Code Skills para extender el agente con instrucciones reutilizables.
La doc oficial de statusline está en code.claude.com/docs/en/statusline y se actualiza con frecuencia, así que merece la pena pasar por ahí cada par de releases.
