Claude Code Statusline: rutas, campos, scripts y solucion de fallos

Claude Code statusline es un comando local. Claude Code envia el JSON de la sesion a stdin, tu comando imprime texto en stdout, y ese texto se convierte en la linea inferior de la interfaz. Usa /statusline para una primera version personal, configura statusLine manualmente cuando necesites revisar el script, y lleva la configuracion al proyecto solo cuando el comando sea seguro para todos.

El orden seguro no empieza por el estilo. Primero decide la ruta, despues confirma el contrato stdin/stdout, luego el alcance de settings, y solo entonces elige los campos. La statusline puede mostrar modelo, directorio, rama git, uso de context, estimacion de cost y, en algunos casos, datos de rate limit. Aun asi, el script debe tratar cada campo como opcional.

Entiende primero el contrato de statusline

Statusline no es un tema de terminal y no es otra llamada a la API. Es una superficie de comando dentro de Claude Code. Claude Code ejecuta tu comando local, escribe JSON en stdin, lee stdout y muestra ese resultado como la linea inferior.

Esto cambia la forma de pensar. Primero, el comando corre en tu maquina. Puede invocar git, leer archivos o ejecutar un script en tu home. Eso es util para uso personal, pero en project settings se convierte en una frontera de confianza para todo el equipo.

Segundo, el script debe ser defensivo. El JSON puede traer model, workspace, git, cost, context, session, version, output style, vim, agent, worktree y rate-limit data. Pero no todos los campos existen en todas las cuentas, versiones o rutas. Un buen script imprime ctx:? o git:- en vez de romperse.

Tercero, stdout es la superficie visible. Los logs de debug van a stderr. La linea final debe ser corta, estable y rapida.

Usa /statusline para una primera version

Ejecuta dentro de Claude Code:

text
/statusline

Pide algo concreto y pequeno:

text
Show model, current directory, git branch, context percentage, and estimated cost. Keep it one line and handle missing fields.

Claude Code puede generar e instalar el script. Cuando funcione, abre el archivo y leelo. Estas aprobando un comando local, no solo un color. Si ves rutas absolutas de una maquina, llamadas de red, endpoints privados o trabajo lento, no lo conviertas en estandar del equipo.

/statusline sirve para explorar que informacion vale la pena. Cuando quieras una convencion compartida, vuelve a statusLine manual y revisa path, fallback, velocidad y confianza.

Configura statusLine manual cuando necesitas control

La configuracion manual vive como un command object:

json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline/statusline.js",
    "refreshInterval": 5
  }
}

Los campos centrales son type y command. refreshInterval es opcional. Usalo solo si una parte de la linea necesita refresco por tiempo, como un reloj o un estado cacheado externo. En la mayoria de los casos Claude Code ya actualiza por eventos, y un intervalo demasiado agresivo solo hace mas visible un script lento.

Para uso personal, ~/.claude/ esta bien. Para un proyecto, el script puede vivir en .claude/statusline/, pero debe revisarse como codigo. No pongas secrets, endpoints privados ni rutas de una persona en shared project settings.

Prueba el script con mock JSON antes de activarlo

Un starter script en Node.js puede leer stdin, parsear JSON y escribir una sola linea:

js
#!/usr/bin/env node

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});

process.stdin.on("end", () => {
  let data = {};
  try {
    data = input.trim() ? JSON.parse(input) : {};
  } catch (error) {
    console.error(`statusline JSON parse failed: ${error.message}`);
  }

  const model = data.model?.display_name || data.model?.id || "model?";
  const cwd = data.workspace?.current_dir || data.cwd || "";
  const dir = cwd ? cwd.split("/").filter(Boolean).pop() : "workspace?";
  const branch = data.git?.branch ? `git:${data.git.branch}` : "git:-";
  const context =
    typeof data.context_window?.percentage === "number"
      ? `ctx:${Math.round(data.context_window.percentage)}%`
      : "ctx:?";
  const cost =
    typeof data.cost?.total_cost_usd === "number"
      ? `$${data.cost.total_cost_usd.toFixed(2)} est`
      : "$? est";

  process.stdout.write(`${model} | ${dir} | ${branch} | ${context} | ${cost}`);
});

Pruebalo sin Claude Code:

bash
chmod +x ~/.claude/statusline/statusline.js
printf '%s' '{"model":{"display_name":"Claude Sonnet"},"workspace":{"current_dir":"/Users/me/project"},"git":{"branch":"main"},"context_window":{"percentage":42},"cost":{"total_cost_usd":0.18}}' | ~/.claude/statusline/statusline.js

Si no produce una linea limpia fuera de Claude Code, arregla el script antes de tocar settings. La prueba externa separa errores de path, permisos, JSON y stdout.

Elige campos por utilidad, no por cantidad

Una statusline debe reducir cambios de contexto. La pregunta practica es simple: que modelo estoy usando, en que workspace estoy, si git esta limpio, cuanto context queda y si el cost estimate esta creciendo.

Un primer formato razonable:

text
Sonnet | api-docs | main* | ctx:42% | $0.18 est

Si no necesitas cost, quitalo. Si git status es lento, muestra solo branch. La linea debe ser util mientras trabajas, no un inventario completo del JSON.

El alcance de settings decide si se puede compartir

Claude Code tiene settings de usuario, locales de proyecto, compartidos de proyecto, managed settings y overrides de sesion. Statusline debe vivir donde el comando sea seguro.

Para equipo:

json
{
  "statusLine": {
    "type": "command",
    "command": "./.claude/statusline/statusline.js"
  }
}

El script compartido debe ser rapido, sin secrets, sin red privada, con fallback y facil de desactivar.

Mantén las actualizaciones rapidas

Statusline se ejecuta repetidamente. No debe ser un monitor pesado. Usa primero los campos que Claude Code ya envio. Cachea checks caros, especialmente git en repos grandes. Usa refreshInterval solo cuando un valor realmente necesita refresco por tiempo.

Mide el script:

bash
time printf '{}' | ~/.claude/statusline/statusline.js

Si es lento aqui, tambien sera lento dentro de Claude Code. Reduce llamadas de red, evita calculos grandes y acorta la linea.

Windows y rendering de terminal

En Windows suele fallar shell/path antes que JSON. Git Bash, PowerShell, WSL y Node manejan comillas y rutas de forma distinta. Prueba exactamente el comando que Claude Code ejecutara.

Empieza con texto plano. Colores ANSI, powerline glyphs y enlaces OSC 8 deben llegar al final. Si funciona en macOS pero no en Windows, revisa interpreter path, executable path, line endings y cwd.

Cuando usar un third-party formatter

Un formatter ayuda si necesitas temas, powerline layout o formato listo. Pero sigue siendo un comando local, no la fuente del contrato oficial.

Si no puedes explicar que ejecuta, manten un script pequeno propio.

Diagnostico de salida vacia, skipped o stale

disableAllHooks tambien pertenece al diagnostico. No lo trates como interruptor aleatorio; puede cambiar comportamiento que esperabas.

Guias relacionadas de Claude Code

• Instalar la CLI: Claude Code install.
• Rutas y credenciales: Claude Code API configuration.
• API key frente a subscription billing: Claude Code API key vs subscription billing.
• Contexto persistente: Claude Code memory.
• Workflows reutilizables: Claude Code best skills.

Preguntas frecuentes

statusline y statusLine son lo mismo?

No. statusline es la frase comun, /statusline es el slash command y statusLine es la clave JSON de settings.

Una statusline usa API tokens?

El comando corre localmente y no hace otra solicitud al modelo. Solo muestra datos que Claude Code ya paso.

Puede mostrar rate limits?

Si el route y la cuenta exponen esos datos, si. El script debe funcionar aunque rate_limits falte.

Puedo commitear el script?

Solo si es seguro para todos: sin secrets, rapido, path-safe, con fallback, revisado y facil de apagar.

Por que veo undefined?

El script asumio que un campo existia. Prueba con mock JSON sin ese campo y agrega fallback.

Cual es la mejor primera linea?

Modelo, basename del directorio, rama git, context percentage y cost estimate si existen. Colores y formatter despues.