- 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 su script con datos de sesión JSON en stdin y muestra lo que el script imprime en stdout. Cuándo se actualiza Su script se ejecuta una vez cuando comienza una sesión, incluyendo cuando reanuda una. Después de eso, se ejecuta nuevamente cuando:- Llega un nuevo mensaje del asistente
/compactfinaliza- El modo de permiso cambia
- El modo Vim se activa o desactiva
- Cambia el
commanden su configuración destatusLine - Un temporizador
refreshIntervalse agota, si establece uno - Una ventana de límite de velocidad en los datos que su script recibió por última vez alcanza su tiempo
resets_at - Un caché de prompt cálido en los datos que su 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 su script aún se está ejecutando, Claude Code cancela el script en vuelo. Si edita su 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 en subagentes de fondo. Para mantener los segmentos basados en tiempo o de fuentes externas actualizados durante períodos de inactividad, establezca refreshInterval para también volver a ejecutar el comando en un temporizador fijo.
Lo que su script puede generar
- Múltiples líneas: cada declaración
echooprintse muestra como una fila separada. Vea el ejemplo de múltiples líneas. - Colores: use códigos de escape ANSI como
\033[32mpara verde (la terminal debe admitirlos). Vea el ejemplo de estado de git. - Enlaces: use 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. Vea el ejemplo de enlaces clickeables.
tput cols y la detección de ancho a nivel de lenguaje no pueden leer el tamaño de la terminal desde dentro del script. Lea las variables de entorno COLUMNS y LINES en su lugar. Claude Code establece estas en las dimensiones actuales de la terminal antes de ejecutar su script.
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 los avisos de permisos.
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 y Max, o detrás de una puerta de aplicaciones Claude que establece un límite de gasto para ti, y 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 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 el uso del límite de velocidad de suscripción de Claude.ai en la línea de estado. El objetorate_limits contiene 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 una puerta de enlace de aplicaciones Claude con límites de gasto, rate_limits lleva spend_limit con los mismos dos campos para el límite de gasto que se aplica a ti, excepto que su used_percentage puede superar 100 una vez que excedas el límite. Requiere Claude Code v2.1.251 o posterior.
El objeto rate_limits solo está presente para suscriptores de Claude.ai Pro y Max, o detrás de una puerta de enlace de aplicaciones Claude con límites de gasto, y solo después de la primera respuesta de API. Cada script maneja el campo ausente con elegancia:
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. Cada tarea tiene id, name, type, status, description, label, startTime, model, effort, contextWindowSize, tokenCount, tokenSamples, y cwd.
El campo model por tarea es el ID de modelo resuelto en el que se ejecuta la tarea. contextWindowSize es la ventana de contexto de ese modelo en tokens, calculada de la misma manera que context_window.context_window_size de la línea de estado principal, por lo que puedes renderizar un porcentaje por fila desde tokenCount. Ambos campos requieren Claude Code v2.1.205 o posterior y se omiten para una tarea cuyo modelo aún no está resuelto.
El campo effort por tarea es el esfuerzo de razonamiento establecido para ese subagente, en su frontmatter de definición o en la invocación individual. El valor es uno de los strings de nivel de esfuerzo low, medium, high, xhigh, o max, o un presupuesto de tokens numérico. El campo reporta el valor configurado tal como está escrito: si el modelo no admite ese nivel, el esfuerzo que Claude Code realmente aplica puede diferir. El campo requiere Claude Code v2.1.214 o posterior y está ausente cuando el subagente hereda el nivel de esfuerzo de la sesión.
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.
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
La línea de estado no aparece- 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 la configuración o establécela enfalseen el archivo que la 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 esta configuración 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
-- o valores vacíos
- Los campos pueden ser
nullantes de que se complete la primera respuesta de API - Maneja valores nulos en tu script con valores predeterminados de respaldo como
// 0en jq - Reinicia Claude Code si los valores permanecen vacíos después de múltiples mensajes
- Usa
used_percentagepara el estado de contexto más simple y preciso - El porcentaje de contexto puede diferir de la salida
/contextdebido a cuándo se calcula cada uno
- 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 anular 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
- Las secuencias de escape complejas (colores ANSI, enlaces OSC 8) pueden ocasionalmente causar salida garbled si se superponen con otras actualizaciones de la interfaz
- Si ves texto corrupto, intenta simplificar tu script a salida de texto plano
- 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
- Debido a que
statusLineejecuta 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, la línea de estado permanece en blanco, y
claude --debugregistraStatus line command skipped: workspace trust not accepted. Reinicia Claude Code y acepta el diálogo de confianza para habilitarlo.
- 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 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
- En terminales estrechas, estas notificaciones pueden truncar tu salida de línea de estado