Statusline de Claude Code: configúrala con /statusline (2026)
Convierte la parte inferior de tu terminal en un panel en vivo — modelo, barra de ventana de contexto, rama de git, carpeta y coste. Doce pasos ilustrados desde el comando /statusline integrado hasta una barra pulida y con color, más las soluciones cuando no aparece.
Lo esencial
- /statusline viene integrado en Claude Code. Ejecútalo, describe la barra que quieres en una frase y un agente statusline-setup escribe el script y deja conectado el bloque statusLine en ~/.claude/settings.json por ti.
- En Windows el agente ofrece tres caminos: convertir tu perfil de PowerShell, apuntar a una configuración de WSL o Git Bash, o montar una por defecto con usuario, directorio, modelo y uso de contexto.
- El script lee un documento JSON por stdin — model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd y más — y todo lo que imprima con echo se convierte en tu barra. Los colores ANSI y varias filas son totalmente válidos.
- Todo corre en local y no cuesta tokens. Las actualizaciones se disparan con los eventos de sesión (o cada N segundos con refreshInterval), y /statusline clear lo elimina todo cuando quieres empezar de cero.
How to Set Up a Custom Status Line in Claude Code CLI to Track API Costs and Context Usage (2026)
Canal:ProgrammingKnowledge23:32
Claude Code最該裝的不是Skill，是這個腳本｜彩色進度條、費用、git 分支一眼看完
Canal:YAHA學堂8:44
Your Claude Code Terminal Should Look Like This (Status Line Setup)
Canal:Leon van Zyl9:02
How to Add a Custom Status Line in Claude Code on Windows 11 (Project-Level Setup)
Canal:Devtamin7:27
Status line — Claude Code documentation
Docs:code.claude.com
Los pasos 1 a 4 se grabaron en Windows PowerShell y los pasos 5 a 12 en macOS; los fotogramas proceden únicamente de grabaciones de pantalla limpias — se excluyeron los que llevaban cámara del creador o overlays incrustados.
Los consejos de configuración — indicar tu sistema operativo, mantener el script global y en su propio archivo, el requisito de jq y el truco del archivo de depuración — vienen de los dos vídeos adicionales acreditados arriba. Los nombres de campos y el comportamiento de refresco de las secciones a fondo siguen la documentación oficial de la línea de estado.
El recorrido de /statusline — 12 pasos ilustrados
Ejecuta /statusline y deja que Claude lo conecte
- 1
Abre Claude Code en tu terminal
Lanza claude en PowerShell, Terminal o cualquier shell. Una sesión recién estrenada solo muestra la caja de bienvenida y un prompt vacío — la franja bajo la entrada, donde vivirá tu statusline, no existe hasta que se añade un bloque statusLine a ~/.claude/settings.json.
Una sesión recién abierta de Claude Code v2.1.83 en Windows PowerShell — caja de bienvenida, prompt vacío, todavía sin línea de estado.Ver en 0:22 - 2
Escribe el comando /statusline
El menú de comandos slash lo describe sin rodeos: configurar la interfaz de línea de estado de Claude Code. Pulsa Enter. Este comando integrado entiende lenguaje natural, así que nunca tienes que escribir un script a mano — aunque luego puedes editar todo lo que genere.
El autocompletado presenta /statusline como el comando que configura la interfaz de línea de estado de Claude Code.Ver en 0:32 - 3
Responde las preguntas del agente de configuración
Un agente específico statusline-setup toma el control. En Windows informa de que no encontró una configuración de shell estándar y ofrece tres caminos: pegar tu perfil PS1 para convertirlo, apuntar a una configuración de WSL o Git Bash, o tomar una por defecto con usuario, directorio, modelo y uso de contexto. Los tres acaban en el mismo bloque de settings.json.
Las tres opciones de Windows del agente: convertir un PS1, apuntar a una configuración propia o partir de una por defecto sensata.Ver en 1:20 - 4
Revisa la configuración y el script que escribió
Cuando el agente termina, imprime una vista previa de la barra — usuario, directorio, rama de git, modelo, porcentaje de contexto — y dice exactamente dónde quedó todo: la configuración en ~/.claude/settings.json y el script en ~/.claude/statusline-command.sh. En macOS y Linux el mismo flujo puede convertir tu prompt existente de .zshrc o .bashrc en vez de empezar de cero.
Configuración confirmada con una vista previa de hardik | ~/Dev/project | main | Claude Opus 4.6 | ctx:42% y ambas rutas de archivo.Ver en 3:06
Describe la barra que quieres en lenguaje natural
- 5
Pide exactamente la barra que quieres
Vuelve a ejecutar /statusline cuando quieras y describe la barra en una frase: muestra el nombre del modelo y el porcentaje de contexto con una barra de progreso. Las peticiones en otros idiomas también funcionan — el comando no es más que un prompt para el agente. Cada nueva petición reescribe el mismo script en vez de acumular duplicados.
Una petición en lenguaje natural — nombre del modelo más barra de progreso del porcentaje de contexto — es toda la interfaz.Ver en 1:07 - 6
Observa la herramienta statusline-setup en acción
Claude Code despacha una herramienta integrada statusline-setup que lee tu ~/.claude/settings.json y tu script de statusline actuales, y luego los reescribe. La tarjeta al pasar el ratón de Claude resume la función: configurar una barra de estado personalizada para vigilar el uso de la ventana de contexto, los costes y el estado de git.
La herramienta statusline-setup a mitad de ejecución, leyendo settings y script, con la descripción de la función al pasar el ratón.Ver en 1:12 - 7
Estrena tu nueva barra
Al terminar, el agente repasa el diseño — nombre del modelo en cian negrita, una barra de contexto de veinte caracteres que se mantiene verde hasta el 49 %, pasa a amarillo en el 50 % y a rojo en el 80 % — y la barra ya está activa en la parte inferior de tu terminal. Sin reiniciar; pide los ajustes en la misma sesión.
El repaso del agente sobre la barra Opus 4.6 (1M de contexto) en vivo, marcando un 2 % de contexto.Ver en 1:27
Lee el script que generó
- 8
Llega un documento JSON por stdin
Abre el script generado — ~/.claude/statusline.sh en macOS y Linux, o la variante .ps1 / statusline-command.sh en Windows. En cada actualización Claude Code canaliza un snapshot JSON de la sesión hacia la entrada estándar del script. El Bash generado lo parsea con jq: .model.display_name, .workspace.current_dir, .cost.total_cost_usd, .cost.total_duration_ms y .context_window.used_percentage.
El parser: cinco lecturas jq sobre stdin y después un BAR_COLOR elegido en los umbrales del 90 % y el 70 % de contexto.Ver en 5:46 - 9
Todo lo que imprimas con echo se convierte en la barra
El final del script es pura presentación: el coste formateado con printf, los milisegundos convertidos a minutos y segundos, y un echo por cada fila de la statusline — modelo con carpeta y rama de git en la primera; barra, porcentaje, coste y cronómetro en la segunda. Los códigos de color ANSI son bienvenidos, y cada echo extra simplemente añade una fila.
Dos líneas echo, dos filas: modelo con directorio y rama, luego barra, porcentaje, coste y cronómetro.Ver en 6:13 - 10
Añade la conciencia de git del mismo modo
Los datos de git están a un subproceso de distancia: git rev-parse --git-dir detecta un repositorio, git branch --show-current nombra la rama, y git diff --cached --numstat y --numstat cuentan los archivos en staged y los modificados. Los ejemplos generados colorean los contadores staged de verde y los modificados de amarillo — un seguro barato si mantienes varias sesiones de Claude Code abiertas en distintas ramas.
GIT_STATUS montado a partir de los contadores staged y modified, coloreado en verde y amarillo con códigos ANSI.Ver en 5:01
Toma el control: clear, reescritura, varias líneas
- 11
Todo cuelga de un solo bloque de settings.json
Echa un vistazo a ~/.claude/settings.json: toda la función cabe en un objeto statusLine — type "command" más el comando a ejecutar, bash ~/.claude/statusline-command.sh en este montaje. Ejecuta /statusline clear y el agente retira el bloque; describe una barra nueva y lo reescribe. Un .claude/settings.json a nivel de proyecto también vale, si quieres una barra por repo.
Un diff de /statusline clear: el bloque statusLine sale de settings.json, listo para reescribirse.Ver en 1:41 - 12
Pásate a varias líneas con coste, duración y enlaces del repo
Las filas se apilan gratis: el ejemplo multilínea de la documentación oficial imprime un enlace de repo clicable mediante secuencias de escape OSC 8, y después una segunda fila con la barra de contexto, el coste de sesión formateado con printf '$%.2f' y los minutos y segundos transcurridos. Umbrales, porcentajes de rate limit, modo vim — pide cualquier combinación e itera hasta que el panel encaje.
Un ejemplo anotado: un enlace de repo OSC 8 en la línea uno; barra, coste y duración en la línea dos.Ver en 7:31
El JSON de stdin que recibe tu script de statusline
Claude Code llama a tu script con un snapshot JSON de la sesión por la entrada estándar. Estos son los campos que conviene conocer, según la documentación oficial — menciona cualquiera en una frase al usar /statusline y el agente lo conecta por ti:
- 1Lo básico de la sesión — session_id, transcript_path, cwd y version, más session_name y prompt_id una vez que enviaste un prompt.
- 2model.id y model.display_name — el modelo de Claude activo que tu barra suele encabezar.
- 3workspace.current_dir, workspace.project_dir y workspace.added_dirs, más workspace.git_worktree y repo.owner / repo.name cuando la carpeta pertenece a un repositorio alojado.
- 4context_window.used_percentage y remaining_percentage — la cifra usada cuenta tokens de entrada, de creación de caché y de lectura de caché, pero no los de salida.
- 5context_window.current_usage lo desglosa en input_tokens, output_tokens, cache_creation_input_tokens y cache_read_input_tokens; es null antes de la primera llamada a la API y justo después de /compact.
- 6cost.total_cost_usd, cost.total_duration_ms, cost.total_api_duration_ms, cost.total_lines_added y cost.total_lines_removed para barras de gasto y ritmo.
- 7rate_limits.five_hour y rate_limits.seven_day con used_percentage y resets_at en los planes Pro/Max (en montajes con gateway aparece una pareja spend_limit) — cada ventana puede faltar por separado, así que protégete en el script.
- 8Extras — exceeds_200k_tokens, fast_mode, effort.level, thinking.enabled, output_style.name, vim.mode, agent.name, pr.number / pr.url / pr.review_state y la familia worktree.*.
Los nombres de campos siguen la documentación oficial de la línea de estado, que también trae scripts listos para Bash, Python y Node.js, una variante para Windows PowerShell y una receta de git cacheado para máquinas lentas.
Solución de problemas: statusline ausente, errónea o desactualizada
Casi todos los fallos de la statusline se reducen a una de cinco causas. Todas se arreglan desde la misma sesión — no hace falta reinstalar nada.
- 1No aparece nada — revisa primero el JSON de ~/.claude/settings.json; en un montaje de Windows grabado, la barra siguió callada hasta corregir un carácter suelto en la ruta del comando y reiniciar la sesión. La barra también se oculta mientras hay prompts de permiso abiertos, y un workspace debe ser de confianza antes de que corran los scripts.
- 2Barra en blanco sin error — tu script terminó con un código distinto de cero o no imprimió nada. Ejecútalo a mano, p. ej. echo '{"model":{"display_name":"Opus"}}' | bash ~/.claude/statusline.sh, y lee la salida; claude --debug también registra el stderr del script.
- 3Solo funciona en un proyecto — el bloque acabó en un .claude/settings.json de proyecto en lugar de tu carpeta personal. Muévelo a ~/.claude/settings.json para tener barra en todos los proyectos.
- 4Los números no cuadran — el script seguramente lee la propiedad equivocada. Pide a Claude que vuelque el JSON crudo de stdin a un archivo de depuración, lee ese archivo y corrige el campo; la sesión de macOS grabada arregló su propio porcentaje exactamente así.
- 5El script existe pero no pinta nada en macOS o Linux — falta jq. Instálalo (brew install jq, sudo apt install jq o el equivalente en Windows) y pide a Claude que actualice la línea de estado para que el script se regenere contra él.
Con qué frecuencia se refresca la barra (y lo que cuesta)
El script corre una vez al arrancar la sesión y luego cada vez que pasa algo: un mensaje nuevo del asistente, la conclusión de un /compact, un cambio de modo de permiso o de modo vim, una edición del propio comando, un reinicio de ventana de rate limit o la caducidad de una caché de prompt todavía caliente. Las actualizaciones van amortiguadas a 300 milisegundos, y una ejecución en marcha se cancela cuando llega otra más nueva.
Como las actualizaciones dependen de eventos, la barra puede quedarse callada mientras esperas — un subagent con una tarea larga, por ejemplo. Añade refreshInterval al bloque statusLine para relanzar el script cada N segundos con datos temporales. Nada de esto toca la API: el script corre en local y no consume tokens, y cada línea echo extra se pinta como una fila más.
Dos diales más para curiosos: hideVimModeIndicator suprime el texto integrado -- INSERT -- si tu script pinta el modo vim por su cuenta, y un ajuste aparte llamado subagentStatusLine da a los subagents sus propias filas personalizadas en el panel del agente.