Claude Code statusline: configura la barra de estado y corrige fallos
Usa /statusline para crear una barra personal o configura statusLine con un script propio. Prueba primero su entrada JSON y su salida; después comprueba qué archivo de ajustes se aplica.
En esta página

Para configurar la barra de estado de Claude Code, usa /statusline si quieres que Claude prepare una primera versión, o define statusLine si prefieres controlar el script. El mecanismo es el mismo: Claude Code envía un JSON por la entrada estándar (stdin), ejecuta el comando configurado y muestra el texto que este devuelve por la salida estándar (stdout).
Empieza con modelo, carpeta, rama y contexto. Añade el coste como estimación de la sesión, y la cuota solo cuando el JSON la proporcione. Una prueba con datos ficticios permite comprobar el script antes de conectarlo a la interfaz; más abajo tienes todos los archivos necesarios y el resultado esperado. El contrato y los campos se describen en la documentación oficial de la barra de estado.
| Lo que necesitas | Ruta adecuada | Qué comprobar primero |
|---|---|---|
| Una barra personal sin escribir todo el código | /statusline | Qué script y comando ha generado |
| Un formato pequeño que puedas mantener | Script propio en statusLine | Que lea JSON y produzca texto con la prueba local |
| La misma barra para el equipo | Script del repositorio y ajustes compartidos | Que las rutas y dependencias funcionen para los demás |
| Temas, varias filas y selección de indicadores | Un formateador como ccstatusline | Sus dependencias y cómo obtiene cada dato |
Crea una primera versión con /statusline
Dentro de una sesión de Claude Code, escribe /statusline y describe lo que quieres, por ejemplo:
Muestra el modelo, la carpeta actual, la rama de Git y el porcentaje
usado de contexto. Usa una sola línea y muestra ? si falta un dato.El comando puede generar un script en tu área de configuración y actualizar los ajustes. Revisa el archivo y el comando resultantes: te interesa saber si utiliza solo el JSON recibido, consulta Git o hace algo más. Después comprueba que la barra aparece y que los valores corresponden a la sesión. Esta es la ruta asistida documentada por Claude Code.
Si quieres entender y modificar cada decisión del formato, utiliza la siguiente ruta manual. Para quitar la personalización, puedes pedir a /statusline que la elimine o borrar únicamente la clave statusLine del archivo que la define; conserva el resto de tus ajustes.
Configuración manual: script completo y prueba sin Claude
Este ejemplo utiliza Node.js y, opcionalmente, Git. Comprueba que node --version funciona en la terminal desde la que arrancas Claude Code. Una instalación nativa de Claude Code no garantiza que tengas Node.js instalado aparte. Git solo se necesita para mostrar la rama; si no está disponible, la línea sigue funcionando.
En macOS o Linux, crea la carpeta con:
mkdir -p "$HOME/.claude/statusline"Guarda este contenido completo en ~/.claude/statusline/barra.cjs. En Windows puedes crear la misma carpeta bajo tu directorio de usuario; el apartado de Windows explica el comando y la prueba.
const fs = require("node:fs");
const { execFileSync } = require("node:child_process");
function texto(valor, defecto) {
if (typeof valor !== "string" || !valor.trim()) return defecto;
return valor.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
.replace(/\|/g, "/").trim();
}
function numero(valor) {
return typeof valor === "number" && Number.isFinite(valor);
}
function porcentaje(valor) {
return numero(valor) && valor >= 0 && valor <= 100
? `${Math.round(valor)} %` : "?";
}
function rama(directorio) {
if (typeof directorio !== "string" || !directorio) return "?";
const opciones = {
encoding: "utf8", timeout: 1000, maxBuffer: 4096,
stdio: ["ignore", "pipe", "pipe"]
};
try {
return texto(execFileSync("git", [
"-C", directorio, "symbolic-ref", "--quiet", "--short", "HEAD"
], opciones), "?");
} catch {
try {
const revision = execFileSync("git", [
"-C", directorio, "rev-parse", "--short", "HEAD"
], opciones);
return `@${texto(revision, "?")}`;
} catch {
return "?";
}
}
}
function cuotaCincoHoras(ventana) {
if (!ventana || !numero(ventana.resets_at)
|| ventana.resets_at <= Date.now() / 1000) return "?";
return porcentaje(ventana.used_percentage);
}
let datos;
try {
const entrada = fs.readFileSync(0, "utf8").replace(/^\uFEFF/, "");
datos = entrada.trim() ? JSON.parse(entrada) : {};
if (!datos || typeof datos !== "object" || Array.isArray(datos)) {
throw new Error("Se esperaba un objeto JSON");
}
} catch (error) {
process.stderr.write(`Barra: ${error.message}\n`);
process.stdout.write("barra: entrada inválida\n");
process.exit(1);
}
const modelo = texto(datos.model?.display_name,
texto(datos.model?.id, "modelo:?"));
const directorio = typeof datos.workspace?.current_dir === "string"
&& datos.workspace.current_dir
? datos.workspace.current_dir : datos.cwd;
const carpeta = typeof directorio === "string"
? texto(directorio.split(/[\\/]/).filter(Boolean).pop(), "carpeta:?")
: "carpeta:?";
const contexto = porcentaje(datos.context_window?.used_percentage);
const importe = datos.cost?.total_cost_usd;
const coste = numero(importe) && importe >= 0
? `${importe.toFixed(2).replace(".", ",")} USD estimados`
: "coste:?";
process.stdout.write([
modelo, carpeta, `rama:${rama(directorio)}`,
`ctx:${contexto}`, coste,
`5 h:${cuotaCincoHoras(datos.rate_limits?.five_hour)}`
].join(" | ") + "\n");El script no solicita credenciales ni llama a una API. Lee stdin y consulta la rama con git -C en el directorio recibido, sin modificar el repositorio. La consulta usa argumentos separados, no concatena la ruta en un comando de shell. El límite de un segundo por consulta es una decisión del ejemplo para acotar la espera, no una garantía de velocidad.

Comprueba el resultado con una entrada ficticia
Crea statusline-prueba.json en una carpeta de pruebas con este contenido:
{
"model": {"id": "modelo-de-prueba", "display_name": "Claude Sonnet"},
"workspace": {"current_dir": "/ejemplo/tienda"},
"context_window": {"used_percentage": 42},
"cost": {"total_cost_usd": 0.18},
"rate_limits": {
"five_hour": {"used_percentage": 25, "resets_at": 2100000000}
}
}La ruta y el instante de reinicio son ficticios. El instante está expresado en segundos Unix y se ha elegido en el futuro para mantener activa la ventana de prueba. Ejecuta, desde la carpeta que contiene ese JSON:
node "$HOME/.claude/statusline/barra.cjs" < statusline-prueba.jsonSi /ejemplo/tienda no existe, el resultado esperado es:
Claude Sonnet | tienda | rama:? | ctx:42 % | 0,18 USD estimados | 5 h:25 %La señal de éxito es una línea en stdout, sin mensajes de error y con salida del proceso igual a 0. rama:? es correcto para esta ruta ficticia. Si sustituyes la ruta por un repositorio de pruebas, verás su rama; con HEAD separado de una rama, verás @ y la revisión corta. El ejemplo no calcula si hay archivos modificados.
Prueba también un objeto vacío:
printf '%s' '{}' | node "$HOME/.claude/statusline/barra.cjs"Debe mostrar los indicadores desconocidos sin fallar. Para comprobar la diferencia, cambia used_percentage a 0: debe aparecer 0 %; con null, debe aparecer ?. Si resets_at ya ha pasado, 5 h:? sustituye al porcentaje antiguo. Con JSON mal formado, el proceso devuelve 1 y escribe el diagnóstico en stderr.
Estas comprobaciones verifican el procesamiento de datos ficticios y la salida del script. La aparición de la barra en Claude Code se comprueba después, con la configuración aplicada a tu sesión.
Conecta el comando a tus ajustes
Añade este fragmento a tus ajustes de usuario, conservando las demás claves. En macOS y Linux, la ubicación habitual es ~/.claude/settings.json. Sustituye la ruta de ejemplo por tu ruta absoluta real; si Node no se encuentra en el entorno de Claude Code, utiliza también la ruta absoluta de su ejecutable.
{
"statusLine": {
"type": "command",
"command": "node \"/Users/tu-usuario/.claude/statusline/barra.cjs\""
}
}Invocamos el archivo mediante node, por lo que el script necesita permiso de lectura, no el bit de ejecución de un programa lanzado directamente. Si configuras un ejecutable o un script con su propio intérprete en la primera línea, sus requisitos de ejecución cambian.
El objeto documentado admite type, command y opciones como padding, refreshInterval y hideVimModeIndicator. Para empezar, basta con los dos primeros. El cambio del comando provoca una actualización inmediata; si la barra sigue vacía aunque la prueba funcione, pasa al diagnóstico de ajustes y restricciones. Referencia de statusLine.
Qué significan contexto, coste y cuota
Elige campos que te ayuden a tomar una decisión mientras trabajas. El contexto ocupado, el coste estimado de la sesión y el uso de una ventana de suscripción miden cosas distintas. No deduzcas uno a partir de otro.
| Dato | Campo actual | Interpretación |
|---|---|---|
| Modelo | model.display_name o model.id | model es un objeto, no un nombre plano |
| Directorio actual | workspace.current_dir o cwd | Puede diferir de workspace.project_dir, el directorio de inicio |
| Contexto usado | context_window.used_percentage | Ocupación correspondiente a la última respuesta de la API |
| Coste de sesión | cost.total_cost_usd | Estimación del cliente con precios de referencia, en USD |
| Uso de cinco horas | rate_limits.five_hour.used_percentage | Porcentaje consumido, cuando esa ventana está disponible |
| Reinicio | rate_limits.five_hour.resets_at | Fecha en segundos Unix; no milisegundos |
Los nombres y condiciones anteriores proceden del esquema oficial completo. No hay un campo general git.branch: por eso el script consulta Git. Los datos worktree solo aparecen en los casos correspondientes y su rama puede faltar; no sustituyen una consulta general de cualquier repositorio.
Un contexto desconocido no significa contexto vacío
current_usage y los porcentajes pueden ser null antes de la primera respuesta o, en el caso de current_usage, después de /compact hasta la siguiente respuesta. Mantén la distinción entre un número real y una ausencia. Usar valor || 0 convierte ambas situaciones en el mismo indicador y oculta información.
El porcentaje actual cuenta los tokens de entrada, incluidos los de creación y lectura de caché; no suma los tokens de salida. Describe el contexto vivo de la última respuesta, no todo lo consumido durante la sesión. /context puede dar un valor mayor porque añade una estimación de mensajes nuevos todavía no enviados. Cálculo del contexto en la barra.
Si el contexto crece al recibir respuestas de herramientas, sigue el diagnóstico de cómo liberar contexto de Claude Code con MCP sin perder la tarea. Cambiar el indicador no reduce el contenido que entra en la conversación.
El coste mostrado no es una factura
cost.total_cost_usd es una estimación calculada por el cliente; no prueba cuánto te han cobrado ni identifica al titular de las credenciales. Desde la versión 2.1.211, /clear comienza una nueva sesión con ese contador a 0; versiones anteriores podían conservarlo. Los campos de duración terminados en _ms están expresados en milisegundos. Costes y duración de la sesión.
El ejemplo conserva los USD del dato original. No los convierte a euros ni calcula una supuesta cuota dividiendo tokens por un límite inventado.
La cuota puede faltar aunque todo funcione
rate_limits está disponible para suscripciones claude.ai Pro/Max y para Claude apps gateway con límites de gasto, después de la primera respuesta de la API. Las ventanas five_hour, seven_day y spend_limit pueden faltar por separado, y las vencidas se eliminan. La ausencia no demuestra uso cero, cuota ilimitada ni un fallo de la clave. Disponibilidad de límites en el JSON.
Para añadir la semana, aplica a seven_day la misma comprobación de porcentaje y vencimiento. No reutilices sin cambios esa función para spend_limit: es específico de la pasarela y su porcentaje puede superar el 100 %. Requiere la versión 2.1.251; los campos opcionales used_usd, limit_usd y period necesitan la 2.1.284 tanto en el cliente como en la pasarela. Los importes se obtienen por separado, aproximadamente cada cinco minutos, y pueden ir por detrás del porcentaje. Campos de límite de gasto.
También puedes añadir estadísticas de prompt_cache desde la versión 2.1.251, si el proveedor aporta los contadores necesarios. Se refieren a la conversación principal y no incluyen las llamadas de subagentes. Un indicador de caché, por sí solo, no explica todos los costes ni los fallos de una tarea. Empieza por el formato sencillo y añade ese dato cuando tengas un uso concreto para él. Estadísticas de caché disponibles.
Dónde guardar los ajustes y cuándo compartirlos
Los ajustes de usuario afectan a tus proyectos en esa máquina. Los de proyecto local permiten una preferencia personal; los compartidos permiten distribuir el comportamiento al equipo. Para una misma clave, el orden de prioridad es: ajustes administrados, --settings, proyecto local, proyecto compartido y usuario. Las claves omitidas pueden seguir tomando el valor de un nivel inferior. Ámbitos y prioridad de ajustes.
| Ámbito | Ubicación habitual | Uso de la barra |
|---|---|---|
| Usuario | ~/.claude/settings.json | Tu script y tus preferencias |
| Proyecto local | .claude/settings.local.json | Una excepción personal del proyecto |
| Proyecto compartido | .claude/settings.json | Convención acordada por el equipo |
| Administrado | Ubicación definida por la organización | Configuración sujeta a su política |
En Git y en directorios de trabajo enlazados, el archivo local puede resolverse desde la raíz del directorio de trabajo principal; existen excepciones de plataforma, ubicación y versión. Los ajustes compartidos se leen desde el directorio de trabajo principal de la sesión. No des por hecho que el archivo situado junto a tu terminal es el que se ha cargado: consulta Setting sources en /status. Esa vista enumera archivos cargados, no qué archivo aportó cada clave. Ubicaciones y carga de ajustes.
Para compartir este ejemplo, guarda el script revisado en .claude/statusline/barra.cjs del repositorio y establece un comando accesible al equipo, por ejemplo node .claude/statusline/barra.cjs si lo ejecutáis desde la raíz. Comprueba ese directorio de ejecución antes de adoptar una ruta relativa. No distribuyas una ruta como /Users/tu-usuario/..., ni supongas que todos tienen el mismo intérprete instalado.
Cuándo se actualiza y por qué conserva valores antiguos
Claude Code ejecuta la barra al iniciar o reanudar la sesión, recibir mensajes del asistente, terminar /compact y cambiar ciertos estados de la interfaz. También reacciona al comando configurado, al temporizador opcional y al vencimiento de marcas temporales de cuota o caché que ya ha recibido. Los cambios se agrupan con una espera de 300 ms; una actualización nueva puede cancelar un script que siga ejecutándose. Ciclo de actualización oficial.
Editar el archivo del script hace visible el cambio en el siguiente evento. Si quieres que una rama cambiada desde otra terminal se vea mientras Claude está inactivo, añade al objeto statusLine, por ejemplo:
"refreshInterval": 10Son segundos; el mínimo documentado es 1. Este intervalo vuelve a ejecutar el comando, pero no convierte automáticamente un dato antiguo de la API en una medición nueva. Si el reloj o Git cambian y el contexto sigue igual, pueden estar actualizándose correctamente a partir de fuentes distintas.
Si notas retrasos, elimina primero las consultas añadidas al script y prueba solo con el JSON. No hace falta consultar el estado completo de Git para mostrar una rama. Si incorporas una caché, distingue sesión y directorio para evitar que una sesión muestre el resultado de otra. El tiempo real depende del script, las dependencias y la máquina; no hay aquí una comparación de rendimiento entre Bash, Python y Node.js.
Windows: comprueba intérprete, comillas y ruta
En Windows, la documentación actual utiliza Git Bash cuando está instalado y PowerShell como alternativa. No presupongas que todos los comandos pasan por cmd.exe. Usa barras / en la ruta del comando y conserva las comillas cuando haya espacios. Configuración oficial para Windows.
El mismo archivo barra.cjs puede invocarse con Node. Si tus rutas reales son las siguientes, el objeto sería:
{
"statusLine": {
"type": "command",
"command": "\"C:/Program Files/nodejs/node.exe\" \"C:/Users/Ana/.claude/statusline/barra.cjs\""
}
}No copies esas rutas sin comprobar dónde están Node y tu archivo. En PowerShell, una prueba con el JSON guardado sería:
Get-Content -Raw -Encoding UTF8 .\statusline-prueba.json |
& 'C:\Program Files\nodejs\node.exe' 'C:\Users\Ana\.claude\statusline\barra.cjs'
$LASTEXITCODEBusca la misma línea de prueba y código 0. El script reconoce tanto / como \ al obtener el nombre de la carpeta y elimina un posible marcador BOM al leer JSON. Esto no demuestra el funcionamiento de tu terminal de Windows: comprueba después el comando exacto configurado en Claude Code. Si Git falta en ese entorno, rama:? no impide mostrar los demás datos.
Barra vacía: separa fallo del script, ajustes y restricciones

Si falla la prueba local, arregla primero el comando. Si funciona fuera de Claude Code, comprueba los ajustes cargados y las restricciones aplicables. Una barra oculta durante un aviso de permisos o ayuda puede ser transitoria; espera a la vista normal antes de diagnosticar un fallo permanente. Resolución de problemas de la barra.
| Síntoma | Comprobación que distingue la causa | Siguiente acción |
|---|---|---|
| Error de archivo o intérprete | Ejecuta el comando con el JSON ficticio | Corrige la ruta y comprueba Node en ese entorno |
| El proceso termina pero no hay texto | Separa stdout de stderr | Escribe el resultado en stdout; reserva stderr para diagnósticos |
Aparece undefined o ? solo en un dato | Revisa el nombre y tipo del campo | Usa el esquema actual y conserva los valores ausentes como desconocidos |
| La prueba funciona y la barra no aparece | Mira Setting sources y las políticas aplicables | Localiza la configuración efectiva; consulta al administrador si está restringida |
| Cambias el script y sigue el formato anterior | Provoca el siguiente evento de actualización | Comprueba también que has editado el archivo que invoca el comando |
| Git cambia en otra terminal, pero la barra no | Comprueba si Claude sigue inactivo | Añade un intervalo si necesitas esa actualización en reposo |
| La barra tarda o desaparece durante cambios rápidos | Prueba una versión que solo lea JSON | Reduce trabajo externo; una actualización nueva puede cancelar la anterior |
En una carpeta de pruebas, puedes distinguir las dos salidas así:
node "$HOME/.claude/statusline/barra.cjs" < statusline-prueba.json \
> barra-salida.txt 2> barra-error.txtCon el JSON válido, barra-salida.txt debe contener la línea y barra-error.txt debe estar vacío para este script. Otros scripts pueden escribir diagnósticos legítimos en stderr; no los confundas con el texto que debe mostrar la barra. claude doctor puede informar de entradas de ajustes rechazadas; el arranque interactivo también detecta JSON incorrecto y ciertos valores no válidos. Validación de ajustes.
Restricciones administradas: el comando puede omitirse
Las restricciones de la barra no se reducen a los permisos del archivo:
- Un
disableAllHooks: trueadministrado, o un espacio de trabajo no confiable, desactiva las barras personalizadas. allowManagedHooksOnly, undisableAllHooks: trueefectivo de origen no administrado, o--safe-modelimita la barra a valores definidos en los ajustes administrados. Una barra administrada puede seguir funcionando; una personal o de proyecto puede omitirse sin aviso.- Que la política permita ciertos hooks de un plugin no autoriza su barra: el valor
statusLinedebe proceder de los ajustes administrados cuando se aplica esa restricción.
Estas reglas están en la referencia de restricciones de ajustes. Si la causa es una política de la organización, consulta a su administrador para configurar una barra permitida. Borrar archivos de ajustes o desactivar controles no es una reparación del script.
Texto cortado, colores o enlaces que no funcionan
Vuelve al texto plano y acorta la salida antes de añadir decoración. La barra admite varias líneas, colores ANSI y enlaces OSC 8, pero la terminal puede limitar su presentación; Terminal.app no permite los enlaces OSC 8 pulsables. Las notificaciones y una ventana estrecha también compiten por espacio. Para adaptar la anchura, usa COLUMNS y LINES, que Claude Code proporciona; el proceso no recibe un TTY normal del que puedas obtenerla con tput cols. Formato y anchura de la barra.
Cuándo compensa usar ccstatusline
Elige ccstatusline si quieres configurar temas, distribución en varias filas e indicadores desde una interfaz de terminal. Mantén el script pequeño si te basta con sus campos y prefieres controlar cómo se calculan. Son decisiones de mantenimiento y presentación, no una clasificación universal de velocidad.
El inicio rápido del proyecto utiliza npx -y ccstatusline@latest o bunx -y ccstatusline@latest. Su interfaz ofrece una instalación global con versión fijada que instala el paquete y escribe el comando correspondiente. La configuración propia se guarda en ~/.config/ccstatusline/settings.json. Una vez instalado globalmente, ccstatusline abre esa interfaz; no necesitas un supuesto comando ccstatusline init. Instrucciones del proyecto.
Comprueba cómo obtiene cada indicador antes de activarlo. Algunos de cuota pueden buscar credenciales, acceder al llavero de macOS y consultar la API de uso de Anthropic; otros leen transcripciones o cachés, y los de salud del servicio utilizan la red. Por tanto, no atribuyas a todo el paquete el comportamiento exclusivamente local del script de este artículo. Las capacidades descritas proceden de su documentación; no hemos instalado ni ejecutado el formateador para esta guía.
Preguntas frecuentes
¿/statusline y statusLine son lo mismo?
/statusline es el comando integrado que permite preparar la personalización. statusLine es la clave del archivo de ajustes que define qué comando se ejecuta. «Statusline» también se utiliza como nombre común de la barra. Si buscas automatizar otro tipo de tarea, consulta cuándo elegir un hook, un comando de barra o una skill.
¿La barra gasta tokens del modelo cada vez que se actualiza?
El script de este ejemplo no hace solicitudes al modelo: procesa JSON y consulta Git. Un script distinto puede realizar más acciones. Además, pedir a /statusline que genere o modifique el código y usar un formateador con consultas externas son actividades diferentes de imprimir la línea local. Mecanismo de la barra y obtención de datos de ccstatusline.
¿Por qué no veo mi cuota si sí veo el modelo?
La disponibilidad de rate_limits depende de la cuenta y la ruta: se documenta para claude.ai Pro/Max y Claude apps gateway con límites de gasto, después de la primera respuesta. Una ventana ausente o vencida no equivale a cuota infinita. Mantén ? u omite ese indicador. Campos de límites.
¿Puedo compartir el script sin compartir mis ajustes personales?
Sí. Guarda el script revisado en el repositorio y deja tu comando en los ajustes de usuario o locales. Si el equipo acuerda compartir también statusLine, comprueba las rutas, Node y las restricciones de la organización. No necesita credenciales para ejecutar el ejemplo. Ámbitos de ajustes.
Fuentes4
Páginas externas que cita esta guía, en el orden en que aparecen. Última actualización: 8 oct 2026.
Fuentes4
Páginas externas que cita esta guía, en el orden en que aparecen. Última actualización: 8 oct 2026.





