- Desea monitorear el uso de la ventana de contexto mientras trabaja
- Necesita rastrear los costos de la sesión
- Trabaja en múltiples sesiones y necesita distinguirlas
- Desea que la rama de git y el estado siempre sean visibles
esc para interrumpir, la alternativa ? para atajos de teclado, y la sugerencia de mantener espacio para hablar dictado por voz. Para agregar insignias de enlaces interactivos al pie de página cuando aparece una ID en la conversación, sin escribir un script, configure footerLinksRegexes en su lugar.
Aquí hay un ejemplo de una línea de estado de múltiples líneas que muestra información de git en la primera línea y una barra de contexto codificada por colores en la segunda.

Configurar una línea de estado
Usa el comando/statusline para que Claude Code genere un script para ti, o crea manualmente un script y agrégalo a tu configuración.
Usar el comando /statusline
El comando/statusline acepta instrucciones en lenguaje natural que describen lo que deseas mostrar. Claude Code genera un archivo de script en ~/.claude/ y actualiza tu configuración automáticamente:
Configurar manualmente una línea de estado
Agrega un campostatusLine a tu configuración de usuario (~/.claude/settings.json, donde ~ es tu directorio de inicio) o configuración del proyecto. Establece type en "command" y apunta command a una ruta de script o un comando de shell en línea. Para un tutorial completo sobre cómo crear un script, consulta Construir una línea de estado paso a paso.
command se ejecuta en un shell, por lo que también puedes usar comandos en línea en lugar de un archivo de script. Este ejemplo usa jq para analizar la entrada JSON y mostrar el nombre del modelo y el porcentaje de contexto:
padding opcional agrega espaciado horizontal adicional (en caracteres) al contenido de la línea de estado. Por defecto es 0. Este relleno se suma al espaciado integrado de la interfaz, por lo que controla la indentación relativa en lugar de la distancia absoluta desde el borde de la terminal.
El campo refreshInterval opcional vuelve a ejecutar tu comando cada N segundos además de las actualizaciones impulsadas por eventos. El mínimo es 1. Establece esto cuando tu línea de estado muestra datos basados en tiempo, como un reloj, o cuando los subagentes de fondo cambian el estado de git mientras la sesión principal está inactiva. Déjalo sin establecer para ejecutar solo en eventos.
El campo hideVimModeIndicator opcional suprime el texto integrado -- INSERT -- debajo del prompt. Establece esto en true cuando tu script renderiza vim.mode por sí mismo, para que el modo no se muestre dos veces.
Desactivar la línea de estado
Ejecuta/statusline y pídele que elimine o borre tu línea de estado (por ejemplo, /statusline delete, /statusline clear, /statusline remove it). También puedes eliminar manualmente el campo statusLine de tu settings.json.
Construir una línea de estado paso a paso
Este tutorial muestra lo que/statusline configura para ti creando manualmente una línea de estado que muestra el modelo actual, el directorio de trabajo y el porcentaje de uso de la ventana de contexto.
Ejecutar
/statusline con una descripción de lo que deseas configura todo esto automáticamente para ti.
1
Crear un script que lea JSON e imprima salida
Claude Code envía datos JSON a tu script a través de stdin. Este script usa
jq, un analizador JSON de línea de comandos que es posible que necesites instalar, para extraer el nombre del modelo, el directorio y el porcentaje de contexto, luego imprime una línea formateada.Guarda esto en ~/.claude/statusline.sh (donde ~ es tu directorio de inicio, como /Users/username en macOS o /home/username en Linux):2
Hacerlo ejecutable
Marca el script como ejecutable para que tu shell pueda ejecutarlo:
3
Agregar a la configuración
Dile a Claude Code que ejecute tu script como la línea de estado. Agrega esta configuración a Tu línea de estado aparece en la parte inferior de la interfaz. Claude Code recarga la configuración automáticamente y ejecuta tu script tan pronto como guardes el archivo.
~/.claude/settings.json, que establece type en "command" (lo que significa “ejecutar este comando de shell”) y apunta command a tu script:Cómo funcionan las líneas de estado
Claude Code ejecuta tu script con datos de sesión JSON en stdin y muestra lo que el script imprime en stdout.La línea de estado se ejecuta localmente y no consume tokens de API. Se oculta temporalmente durante ciertas interacciones de la interfaz de usuario, incluyendo el menú de ayuda y las solicitudes de permiso.
Cuándo se actualiza la línea de estado
Tu script se ejecuta una vez cuando comienza una sesión, incluyendo cuando reanudas una. Después de eso, se ejecuta nuevamente cuando:- Llega un nuevo mensaje del asistente
/compactfinaliza- El modo de permisos cambia
- El modo Vim se activa o desactiva
- Cambias el
commanden tu configuración destatusLine - Un temporizador
refreshIntervalse agota, si estableces uno - Una ventana de rate limit en los datos que tu script recibió por última vez alcanza su tiempo
resets_at - Una caché de prompt activa en los datos que tu script recibió por última vez alcanza su tiempo
expires_at
command omite el debounce: Claude Code ejecuta el nuevo comando de inmediato. Si una nueva actualización se activa mientras tu script aún se está ejecutando, Claude Code cancela el script en curso. Si editas tu script, los cambios aparecen la próxima vez que un disparador de actualización lo vuelve a ejecutar.
Los disparadores impulsados por eventos pueden quedarse en silencio cuando la sesión principal está inactiva, por ejemplo mientras un coordinador espera a subagentes en segundo plano. Para mantener actualizados los segmentos basados en tiempo o de fuentes externas durante períodos de inactividad, establece refreshInterval para también volver a ejecutar el comando con un temporizador fijo.
Lo que tu script puede generar
Tu script puede imprimir más que una sola línea de texto plano:- Múltiples líneas: cada declaración
echooprintse muestra como una fila separada. Consulta el ejemplo de múltiples líneas. - Colores: usa códigos de escape ANSI como
\033[32mpara verde (la terminal debe admitirlos). Consulta el ejemplo de estado de git. - Enlaces: usa secuencias de escape OSC 8 para hacer que el texto sea clickeable (Cmd+clic en macOS, Ctrl+clic en Windows/Linux). Requiere una terminal que admita hipervínculos como iTerm2, Kitty o WezTerm. Consulta el ejemplo de enlaces clickeables.
Ajustar el tamaño de la salida a la terminal
Claude Code captura la salida de tu script en lugar de conectarla directamente a la terminal, por lo quetput cols y la detección de ancho a nivel de lenguaje no pueden leer el tamaño de la terminal desde dentro del script. Lee las variables de entorno COLUMNS y LINES en su lugar. Claude Code las establece en las dimensiones actuales de la terminal antes de ejecutar tu script.
Datos disponibles
Claude Code envía los siguientes campos JSON a tu script a través de stdin:Esquema JSON completo
Esquema JSON completo
Tu comando de línea de estado recibe esta estructura JSON a través de stdin:Campos que pueden estar ausentes (no presentes en JSON):
session_name: aparece cuando se ha establecido un nombre personalizado con--nameo/rename, o una vez que existe un título de sesión generado por IA. El nombre para mostrar predeterminado, comomy-app-3f, no lo completaprompt_id: aparece solo después de la primera entrada del usuarioworkspace.git_worktree: aparece solo cuando el directorio actual está dentro de un git worktree vinculadoworkspace.repo: aparece solo dentro de un repositorio git con un remotooriginconfiguradoeffort: aparece solo cuando el modelo actual admite el parámetro de esfuerzo de razonamientovim: aparece solo cuando el modo vim está habilitadoagent: aparece solo cuando se ejecuta con la bandera--agento configuración de agente configuradapr: aparece solo mientras se encuentra una PR abierta o una solicitud de fusión de GitLab para la rama actual, y se elimina una vez que se fusiona o se cierra.pr.review_stateypr.kindpueden estar independientemente ausentesworktree: aparece solo mientras la sesión está en una sesión de worktree. Cuando está presente,branchyoriginal_branchtambién pueden estar ausentes para worktrees basados en hooksrate_limits: aparece solo para suscriptores de claude.ai Pro, Max y Ultra, o detrás de un gateway de aplicaciones Claude que establece un límite de gasto para ti. Incluso entonces, aparece solo después de la primera respuesta de API en la sesión. Cada ventana (five_hour,seven_day,spend_limit) puede estar independientemente ausente, y Claude Code elimina una ventana una vez que pasa su tiemporesets_at. Usajq -r '.rate_limits.five_hour.used_percentage // empty'para manejar la ausencia con elegancia.prompt_cache: aparece después de la primera respuesta de API de la conversación principal. Consulta campos de prompt cache
null:context_window.current_usage:nullantes de la primera llamada a API en una sesión, y nuevamente después de/compacthasta que la siguiente llamada a API lo repueblacontext_window.used_percentage,context_window.remaining_percentage: pueden sernullal principio de la sesión
Campos de ventana de contexto
El objetocontext_window describe la ventana de contexto en vivo de la respuesta de API más reciente.
- Totales combinados (
total_input_tokens,total_output_tokens): tokens actualmente en la ventana de contexto.total_input_tokenses la suma deinput_tokens,cache_creation_input_tokens, ycache_read_input_tokens;total_output_tokensson los tokens de salida de la respuesta más reciente. Ambos son0antes de la primera respuesta de API. - Uso por componente (
current_usage): los mismos conteos de tokens desglosados por categoría. Usa esto cuando necesites separar los aciertos de caché de la entrada fresca.
current_usage contiene:
input_tokens: tokens de entrada en contexto actualoutput_tokens: tokens de salida generadoscache_creation_input_tokens: tokens escritos en cachécache_read_input_tokens: tokens leídos del caché
used_percentage se calcula solo a partir de tokens de entrada: input_tokens + cache_creation_input_tokens + cache_read_input_tokens. No incluye output_tokens.
Si calculas el porcentaje de contexto manualmente desde current_usage, usa la misma fórmula de solo entrada para coincidir con used_percentage.
El objeto current_usage es null antes de la primera llamada a API en una sesión, y nuevamente inmediatamente después de /compact hasta que la siguiente llamada a API lo repuebla.
Campos de límite de gasto
Detrás de un gateway de aplicaciones Claude con límites de gasto, el objetorate_limits.spend_limit describe el límite de gasto que se aplica a ti. Aparece después de la primera respuesta de API de la sesión y requiere Claude Code v2.1.251 o posterior. Tu script recibe sus campos en calendarios distintos:
used_percentageyresets_at: llegan con cada respuesta, por lo que están presentes siempre quespend_limitlo esté.used_percentageva de 0 a 100, o por encima de 100 una vez que excedas el límite, yresets_atson los segundos de época Unix cuando se reinicia el período del límite.used_usd,limit_usdyperiod: tu gasto estimado hasta el momento y tu límite en dólares estadounidenses, y el período que cubre el límite, uno dedaily,weeklyomonthly. El gateway calculaused_usda partir de los conteos de tokens, por lo que es una estimación y no un monto facturado. Claude Code los lee del gateway en una solicitud separada, aproximadamente cada cinco minutos mientras envías solicitudes. Los montos en dólares pueden tener unos cinco minutos más de antigüedad queused_percentage, por lo que ambos pueden no coincidir brevemente. Requiere v2.1.284 o posterior tanto en Claude Code como en el gateway.
used_usd, limit_usd y period como opcionales incluso cuando spend_limit esté presente, porque tu script recibe el porcentaje antes que ellos. Lee cada uno con un valor de respaldo en tu script, como jq -r '.rate_limits.spend_limit.used_usd // empty'. Antes de Claude Code v2.1.295, permanecían ausentes si establecías CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, que desactivaba esa solicitud.
Campos de prompt cache
El objetoprompt_cache resume cómo la conversación principal de la sesión está utilizando el prompt cache. Claude Code lo calcula a partir de los conteos de tokens de caché en las respuestas de la API, por lo que funciona en cada proveedor.
El objeto aparece después de la primera respuesta de API de la conversación principal. Claude Code no cuenta las solicitudes de subagente en estas estadísticas. Requiere Claude Code v2.1.251 o posterior.
La tabla enumera cada campo con su significado. Las marcas de tiempo son segundos de época Unix, la misma unidad que rate_limits.*.resets_at. Una línea de estado corta generalmente muestra uno o dos de estos; warm y hit_ratio resumen el estado del caché más directamente.
Claude Code muestra las mismas estadísticas en la terminal, en la línea
Prompt cache (main) del comando /usage.
Causa del último fallo
El objetolast_miss_cause reporta lo que Claude Code identificó como la causa probable del fallo más reciente. Su array causes contiene uno o más nombres de causa, como tools_changed, system_prompt_changed, ttl_expired_5m, o likely_server_side. El objeto es null hasta el primer fallo de la sesión, y nuevamente siempre que Claude Code no pueda identificar una causa para el fallo más reciente. Requiere Claude Code v2.1.260 o posterior.
Dos causas agregan conteos al objeto:
tools_addedytools_removed: contools_changed, cuántas herramientas se agregaron o se eliminaron de la solicitudsystem_char_delta: consystem_prompt_changed, el cambio en la longitud del prompt del sistema, en caracteres
Ejemplos
Estos ejemplos muestran patrones comunes de línea de estado. Para usar cualquier ejemplo:- Guarda el script en un archivo como
~/.claude/statusline.sh(o.py/.js) - Hazlo ejecutable:
chmod +x ~/.claude/statusline.sh - Agrega la ruta a tu configuración
jq para analizar JSON. Python y Node.js tienen análisis JSON integrado.
Uso de ventana de contexto
Muestra el modelo actual y el uso de la ventana de contexto con una barra de progreso visual. Cada script lee JSON desde stdin, extrae el campoused_percentage y construye una barra de 10 caracteres donde los bloques rellenos (▓) representan el uso:

Estado de git con colores
Muestra la rama de git con indicadores codificados por colores para archivos preparados y modificados. Este script usa códigos de escape ANSI para colores de terminal:\033[32m es verde, \033[33m es amarillo, y \033[0m restablece al predeterminado.

Seguimiento de costos y duración
Rastrea los costos de API de tu sesión y el tiempo transcurrido. El campocost.total_cost_usd acumula el costo estimado de todas las llamadas a API en la sesión actual. El campo cost.total_duration_ms mide el tiempo total transcurrido desde que comenzó la sesión, mientras que cost.total_api_duration_ms rastrea solo el tiempo dedicado a esperar respuestas de API.
Cada script formatea el costo como moneda y convierte milisegundos a minutos y segundos:

Mostrar múltiples líneas
Tu script puede generar múltiples líneas para crear una pantalla más rica.
print o echo crea una fila separada:
Enlaces clickeables
Este ejemplo crea un enlace clickeable a tu repositorio de GitHub. Mantén presionado Cmd (macOS) o Ctrl (Windows/Linux) y haz clic para abrir el enlace en tu navegador.
printf '%b' que interpreta escapes de barra invertida de manera más confiable que echo -e en diferentes shells:
Uso de límite de velocidad
Muestra en la línea de estado el uso del rate limit de tu suscripción de claude.ai, o tu gasto frente al límite de gasto de un gateway de aplicaciones Claude. Para los suscriptores, el objetorate_limits puede contener una ventana móvil five_hour y una ventana semanal seven_day. Cada ventana proporciona used_percentage, de 0 a 100, y resets_at, los segundos de época Unix cuando se reinicia la ventana. Detrás de un gateway, lee el objeto spend_limit, descrito en campos del límite de gasto.
El objeto rate_limits solo está presente para suscriptores de claude.ai Pro, Max y Ultra, o detrás de un gateway de aplicaciones Claude con límites de gasto, y solo después de la primera respuesta de API. Cada script maneja con elegancia los campos ausentes y, detrás de un gateway, imprime spend: $314.12 / $500, o spend: 63% mientras los campos en dólares estén ausentes:
Cachear operaciones costosas
Tu script de línea de estado se ejecuta frecuentemente durante sesiones activas. Comandos comogit status o git diff pueden ser lentos, especialmente en repositorios grandes. Este ejemplo cachea información de git en un archivo temporal y solo la actualiza cada 5 segundos.
El nombre del archivo de caché debe ser estable en las invocaciones de línea de estado dentro de una sesión, pero único en sesiones para que las sesiones concurrentes en diferentes repositorios no lean el estado de git cacheado de cada una. Los identificadores basados en procesos como $$, os.getpid(), o process.pid cambian en cada invocación y anulan el caché. Usa el session_id de la entrada JSON en su lugar: es estable durante la vida útil de una sesión y único por sesión.
Cada script verifica si el archivo de caché falta o es más antiguo que 5 segundos antes de ejecutar comandos de git:
Configuración de Windows
En Windows, Claude Code ejecuta comandos de línea de estado a través de Git Bash cuando Git Bash está instalado, o a través de PowerShell cuando Git Bash está ausente. Git Bash trata las barras invertidas sin comillas como caracteres de escape, por lo que una ruta de estilo Windows comoC:\Users\username\script.mjs llega al ejecutor de scripts con sus separadores eliminados y el comando falla sin un error visible. Escribe rutas de archivo en la cadena command con barras diagonales, como se muestra en los ejemplos a continuación. El atajo ~ también funciona y se expande a tu directorio de inicio de Windows.
Para ejecutar un script de PowerShell como tu línea de estado, invócalo mediante powershell. Esto funciona ya sea que Claude Code enrute el comando a través de Git Bash o PowerShell:
Líneas de estado de subagentes
La configuraciónsubagentStatusLine renderiza un cuerpo de fila personalizado para cada subagente mostrado en el panel de agentes debajo del prompt. Úsalo para reemplazar la fila predeterminada name · description · token count con tu propio formato.
columns con el ancho de fila utilizable y un array tasks con una entrada por fila, descrito en Campos de tarea.
Escribe una línea JSON a stdout por cada fila que desees anular, en la forma {"id": "<task id>", "content": "<row body>"}. La cadena content se renderiza tal cual, incluidos colores ANSI e hipervínculos OSC 8. Omite el id de una tarea para mantener el renderizado predeterminado para esa fila; emite una cadena content vacía para ocultarla.
Las mismas puertas de confianza, disableAllHooks, y allowManagedHooksOnly que se aplican a statusLine se aplican aquí. Los plugins pueden enviar una subagentStatusLine predeterminada en su settings.json, pero a diferencia de los hooks, los valores de plugins no se ejecutan bajo allowManagedHooksOnly incluso cuando el plugin está forzadamente habilitado en la configuración gestionada enabledPlugins.
Campos de tarea
Cada entrada del arraytasks describe una fila de subagente con los campos siguientes. Los campos marcados como opcionales se omiten cuando no tienen valor, así que contempla su ausencia en tu script.
Consejos
- Prueba con entrada simulada:
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh - Mantén la salida corta: la barra de estado tiene un ancho limitado, por lo que la salida larga puede truncarse o ajustarse de manera incómoda
- Cachea operaciones lentas: tu script se ejecuta frecuentemente durante sesiones activas, por lo que comandos como
git statuspueden causar retrasos. Consulta el ejemplo de caché para saber cómo manejar esto.
Solución de problemas
Si la línea de estado está en blanco, comienza con La línea de estado no aparece. Una carpeta en la que no has confiado y un script que falla también la dejan en blanco, como se describe en Confianza del espacio de trabajo requerida y Errores de script o bloqueos.La línea de estado no aparece
Si configuraste una línea de estado y no se muestra nada en la parte inferior de la interfaz, revisa estas comprobaciones:- Verifica que tu script sea ejecutable:
chmod +x ~/.claude/statusline.sh - Comprueba que tu script genere salida a stdout, no stderr
- Ejecuta tu script manualmente para verificar que produce salida
- En Windows con Git Bash instalado, es probable que las barras invertidas en la ruta del
commandse consuman como caracteres de escape antes de que se ejecute el script. Usa barras diagonales en la ruta. Consulta Configuración de Windows. - Si
disableAllHooksestruefuera de la configuración administrada después de que se aplica la precedencia de configuración, Claude Code ejecuta solo unstatusLinede la configuración administrada, y sin unstatusLineadministrado la línea de estado está deshabilitada. Elimina el ajuste o establécelo enfalseen el archivo que lo establece para volver a habilitarla. ConsultadisableAllHooks. - Si tu organización establece
allowManagedHooksOnlyen la configuración administrada, tu línea de estado personalizada desaparece sin advertencia: solo puedes obtener una línea de estado de un valorstatusLineen esa configuración administrada. Consulta qué se ejecuta bajoallowManagedHooksOnlypara el comportamiento completo, y pregunta a tu administrador si este ajuste se aplica a ti. - Ejecuta
claude --debugpara registrar el stderr de tu script en cada invocación de línea de estado, y su código de salida en la primera invocación en una sesión - Pídele a Claude que lea tu archivo de configuración y ejecute el comando
statusLinedirectamente para exponer errores
La línea de estado muestra -- o valores vacíos
Los campos pueden ser null antes de que se complete la primera respuesta de API, así que maneja los valores nulos en tu script con valores de respaldo como // 0 en jq. Reinicia Claude Code si los valores permanecen vacíos después de múltiples mensajes.
El porcentaje de contexto muestra valores inesperados
La línea de estado reporta los conteos de la última respuesta de API, mientras que/context agrega una estimación para los mensajes añadidos desde esa respuesta, por lo que /context puede leer más alto hasta la siguiente respuesta. Usa used_percentage para el estado de contexto más simple y preciso. Para la fórmula detrás de used_percentage, consulta Campos de la ventana de contexto.
Los enlaces OSC 8 no son clickeables
Que un enlace sea clickeable depende de tu terminal, de si Claude Code detecta soporte de hipervínculos en ella, de si SSH o tmux eliminan la secuencia de escape y de cómo la imprime tu script:- Verifica que tu terminal admita hipervínculos OSC 8 (iTerm2, Kitty, WezTerm)
- Terminal.app no admite enlaces clickeables
-
Si el texto del enlace aparece pero no es clickeable, Claude Code puede no haber detectado soporte de hipervínculos en tu terminal. Establece la variable de entorno
FORCE_HYPERLINKpara sobrescribir la detección antes de lanzar Claude Code:En PowerShell, establece la variable en la sesión actual primero: - Las sesiones SSH y tmux pueden eliminar secuencias OSC dependiendo de la configuración
-
Si las secuencias de escape aparecen como texto literal como
\e]8;;, usaprintf '%b'en lugar deecho -epara un manejo más confiable de escapes
Problemas de visualización con secuencias de escape
Las secuencias de escape complejas (colores ANSI, enlaces OSC 8) pueden ocasionalmente causar salida distorsionada si se superponen con otras actualizaciones de la interfaz. Las líneas de estado de múltiples líneas con códigos de escape son más propensas a problemas de renderizado que el texto plano de una sola línea. Si ves texto corrupto, intenta simplificar tu script a salida de texto plano.Confianza del espacio de trabajo requerida
Hasta que aceptes el diálogo de confianza del espacio de trabajo, la línea de estado permanece en blanco. Debido a questatusLine ejecuta un comando de shell, Claude Code lo ejecuta bajo la misma regla de confianza del espacio de trabajo que los hooks en archivos de configuración. Aceptar el diálogo para la carpeta, o para un directorio padre cuya confianza se extiende a ella, es suficiente.
Hasta entonces, claude --debug registra Status line command skipped: workspace trust not accepted. Reinicia Claude Code y acepta el diálogo de confianza para habilitarlo.
Errores de script o bloqueos
Claude Code muestra la salida de tu script solo después de que el script termina con código 0:- Los scripts que salen con códigos distintos de cero o no producen salida hacen que la línea de estado se quede en blanco
- Los scripts lentos bloquean la línea de estado de actualizar hasta que se completen. Mantén los scripts rápidos para evitar salida obsoleta.
- Si una nueva actualización se activa mientras un script lento se está ejecutando, el script en vuelo se cancela
- Prueba tu script de forma independiente con entrada simulada antes de configurarlo
Las notificaciones comparten la fila de la línea de estado
Fuera de la representación a pantalla completa, Claude Code muestra notificaciones en la misma fila que tu línea de estado. En la representación a pantalla completa, Claude Code asigna a las notificaciones una fila propia.- Las notificaciones del sistema como errores de servidor MCP y actualizaciones automáticas se muestran en el lado derecho de la fila. Las notificaciones transitorias como la advertencia de contexto bajo también ciclan a través de esta área.
- Habilitar el modo verbose agrega un contador de tokens a esta área, que muestra el tamaño de tu contexto según lo reportó la última respuesta de API, no el conteo por turno junto al indicador de progreso
- En terminales estrechas, estas notificaciones pueden truncar tu salida de línea de estado