Saltar al contenido principal

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.

LaoZhang AI TeamPublicadoActualizado 13 min de lectura
En esta página
Barra de estado ilustrativa de Claude Code con contexto, coste estimado y cuota diferenciados

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 necesitasRuta adecuadaQué comprobar primero
Una barra personal sin escribir todo el código/statuslineQué script y comando ha generado
Un formato pequeño que puedas mantenerScript propio en statusLineQue lea JSON y produzca texto con la prueba local
La misma barra para el equipoScript del repositorio y ajustes compartidosQue las rutas y dependencias funcionen para los demás
Temas, varias filas y selección de indicadoresUn formateador como ccstatuslineSus 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:

bash
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.

js
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.

Esquema de las fuentes del script: JSON de Claude Code, consulta local a Git y salidas de texto y diagnóstico

Comprueba el resultado con una entrada ficticia

Crea statusline-prueba.json en una carpeta de pruebas con este contenido:

json
{
  "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:

bash
node "$HOME/.claude/statusline/barra.cjs" < statusline-prueba.json

Si /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:

bash
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.

json
{
  "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.

DatoCampo actualInterpretación
Modelomodel.display_name o model.idmodel es un objeto, no un nombre plano
Directorio actualworkspace.current_dir o cwdPuede diferir de workspace.project_dir, el directorio de inicio
Contexto usadocontext_window.used_percentageOcupación correspondiente a la última respuesta de la API
Coste de sesióncost.total_cost_usdEstimación del cliente con precios de referencia, en USD
Uso de cinco horasrate_limits.five_hour.used_percentagePorcentaje consumido, cuando esa ventana está disponible
Reiniciorate_limits.five_hour.resets_atFecha 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.

ÁmbitoUbicación habitualUso de la barra
Usuario~/.claude/settings.jsonTu script y tus preferencias
Proyecto local.claude/settings.local.jsonUna excepción personal del proyecto
Proyecto compartido.claude/settings.jsonConvención acordada por el equipo
AdministradoUbicación definida por la organizaciónConfiguració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:

json
"refreshInterval": 10

Son 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:

json
{
  "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:

powershell
Get-Content -Raw -Encoding UTF8 .\statusline-prueba.json |
  & 'C:\Program Files\nodejs\node.exe' 'C:\Users\Ana\.claude\statusline\barra.cjs'
$LASTEXITCODE

Busca 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

Árbol de diagnóstico de una barra vacía: prueba local, comando, ajustes, restricciones y actualización

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íntomaComprobación que distingue la causaSiguiente acción
Error de archivo o intérpreteEjecuta el comando con el JSON ficticioCorrige la ruta y comprueba Node en ese entorno
El proceso termina pero no hay textoSepara stdout de stderrEscribe el resultado en stdout; reserva stderr para diagnósticos
Aparece undefined o ? solo en un datoRevisa el nombre y tipo del campoUsa el esquema actual y conserva los valores ausentes como desconocidos
La prueba funciona y la barra no apareceMira Setting sources y las políticas aplicablesLocaliza la configuración efectiva; consulta al administrador si está restringida
Cambias el script y sigue el formato anteriorProvoca el siguiente evento de actualizaciónComprueba también que has editado el archivo que invoca el comando
Git cambia en otra terminal, pero la barra noComprueba si Claude sigue inactivoAñade un intervalo si necesitas esa actualización en reposo
La barra tarda o desaparece durante cambios rápidosPrueba una versión que solo lea JSONReduce trabajo externo; una actualización nueva puede cancelar la anterior

En una carpeta de pruebas, puedes distinguir las dos salidas así:

bash
node "$HOME/.claude/statusline/barra.cjs" < statusline-prueba.json \
  > barra-salida.txt 2> barra-error.txt

Con 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: true administrado, o un espacio de trabajo no confiable, desactiva las barras personalizadas.
  • allowManagedHooksOnly, un disableAllHooks: true efectivo de origen no administrado, o --safe-mode limita 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 statusLine debe 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.

  1. 1.documentación oficial de la barra de estadocode.claude.com/docs/en/statusline
  2. 2.Referencia de statusLinecode.claude.com/docs/en/settings-reference
  3. 3.Ámbitos y prioridad de ajustescode.claude.com/docs/en/settings
  4. 4.ccstatuslinegithub.com/sirmalloc/ccstatusline