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

> Elige la ruta correcta de Claude Code statusline, prueba el script con mock JSON, agrega context, cost y git con seguridad, y arregla salidas vacias o desactualizadas.

- URL: https://blog.laozhang.ai/es/posts/claude-code-statusline
- Published: 2026-05-19
- Updated: 2026-05-19
- Author: AI Free API Team (https://blog.laozhang.ai/es/about)
- Category: Claude Code
- Tags: Claude Code, Statusline, Developer Tools, CLI, Anthropic

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

![Mapa de rutas de Claude Code statusline](https://blog.laozhang.ai/posts/es/claude-code-statusline/img/cover-codex.webp)

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.

| Ruta | Cuando usarla | Primera prueba |
| --- | --- | --- |
| `/statusline` | Quieres una primera version personal rapidamente | La linea aparece y el script generado es entendible |
| `statusLine` manual | Necesitas un script revisable y fallbacks claros | El comando funciona con mock JSON fuera de Claude Code |
| Project settings | El mismo comportamiento no secreto debe vivir en el repo | Cada teammate puede ejecutar la ruta del comando |
| Third-party formatter | El tema o layout justifica una dependencia | Puedes explicar source, install scope y ejecucion local |

## 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

![Flujo de datos de Claude Code statusline](https://blog.laozhang.ai/posts/es/claude-code-statusline/img/explainer-1-codex.webp)

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

![Matriz de campos de Claude Code statusline](https://blog.laozhang.ai/posts/es/claude-code-statusline/img/explainer-2-codex.webp)

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.

| Grupo | Mostrar | Limite |
| --- | --- | --- |
| Model | Nombre corto del modelo | Un nombre largo rompe la linea |
| Workspace | Basename del directorio | Evita rutas completas personales |
| Git | Branch y dirty state | Cachea checks caros |
| Context window | Porcentaje o senal restante | Puede faltar |
| Cost | Estimacion de sesion | No es verdad de facturacion |
| Rate limits | Remaining/reset si existe | No aparece en todas las rutas |
| Session/version | Datos de debug | Puede ser ruido diario |
| Agent/worktree/vim | Estado de modo | Solo si tu flujo lo necesita |

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.

| Alcance | Buen uso | Riesgo |
| --- | --- | --- |
| User settings | Statusline personal | Otros no tienen tu path |
| Local project settings | Override de una maquina | El equipo no lo ve |
| Shared project settings | Comportamiento comun sin secrets | No debe ejecutar rutas privadas |
| Managed settings | Politica de organizacion | Demasiado pesado para estilo |
| Session/CLI override | Experimentos temporales | No es contrato durable |

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.

| Chequeo | Motivo |
| --- | --- |
| Source y maintainer aceptables | Se ejecuta localmente |
| Install scope claro | Global install afecta varios proyectos |
| Lee official stdin JSON | Private endpoint envejece mal |
| Maneja missing fields | Las rutas no exponen lo mismo |
| Es rapido | Se ejecuta muchas veces |
| Se puede apagar | Diagnosticar debe ser simple |

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

## Diagnostico de salida vacia, skipped o stale

![Escalera de diagnostico Claude Code statusline](https://blog.laozhang.ai/posts/es/claude-code-statusline/img/explainer-3-codex.webp)

| Sintoma | Prueba rapida | Arreglo |
| --- | --- | --- |
| No aparece | Ejecutar comando directo | Path, interpreter, executable bit |
| Fuera funciona | Pasar mock JSON | Trust prompt o scope |
| Salida vacia | Revisar stdout/stderr | Imprimir la linea final en stdout |
| `undefined` | JSON sin campo | Optional chaining y fallback |
| Stale output | Quitar trabajo lento | Cache o refresh acotado |
| Skipped | Revisar debug | Trust, hooks, command failure |
| Falla solo en Windows | Mismo shell/path | Interpreter explicito |
| Colores o links rotos | Volver a plain text | Terminal features al final |

`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](https://blog.laozhang.ai/es/posts/claude-code-install).
- Rutas y credenciales: [Claude Code API configuration](https://blog.laozhang.ai/es/posts/claude-code-api-configuration).
- API key frente a subscription billing: [Claude Code API key vs subscription billing](https://blog.laozhang.ai/es/posts/claude-code-api-key-vs-subscription-billing).
- Contexto persistente: [Claude Code memory](https://blog.laozhang.ai/es/posts/claude-code-memory).
- Workflows reutilizables: [Claude Code best skills](https://blog.laozhang.ai/es/posts/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.