Personaliza tu línea de estado

Configura una barra de estado personalizada para monitorear el uso de la ventana de contexto, costos y estado de git en Claude Code

La línea de estado es una barra personalizable en la parte inferior de Claude Code que ejecuta cualquier script de shell que configures. Recibe datos de sesión JSON en stdin y muestra lo que tu script imprime, dándote una vista persistente y de un vistazo del uso de contexto, costos, estado de git, o cualquier otra cosa que desees rastrear.

Las líneas de estado son útiles cuando:

• Deseas monitorear el uso de la ventana de contexto mientras trabajas
• Necesitas rastrear los costos de la sesión
• Trabajas en múltiples sesiones y necesitas distinguirlas
• Deseas que la rama de git y el estado siempre sean visibles

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.

Esta página te guía a través de configurar una línea de estado básica, explica cómo fluyen los datos desde Claude Code a tu script, enumera todos los campos que puedes mostrar, y proporciona ejemplos listos para usar para patrones comunes como estado de git, seguimiento de costos y barras de progreso.

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:

/statusline show model name and context percentage with a progress bar

Configurar manualmente una línea de estado

Agrega un campo statusLine 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.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

El campo 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:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

El campo 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 está sucediendo bajo el capó 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.

Estos ejemplos usan scripts de Bash, que funcionan en macOS y Linux. En Windows, consulta Configuración de Windows para ejemplos de PowerShell y Git Bash.

#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)

# Extract fields using jq
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Output the status line - ${DIR##*/} extracts just the folder name
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"

chmod +x ~/.claude/statusline.sh

{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}

Cómo funcionan las líneas de estado

Claude Code ejecuta tu script y canaliza datos de sesión JSON a través de stdin. Tu script lee el JSON, extrae lo que necesita e imprime texto a stdout. Claude Code muestra lo que tu script imprime.

Cuándo se actualiza

Tu script se ejecuta después de cada nuevo mensaje del asistente, después de que /compact finaliza, cuando cambia el modo de permiso, o cuando se activa/desactiva el modo vim. Las actualizaciones se debounce en 300ms, lo que significa que los cambios rápidos se agrupan y tu script se ejecuta una vez que las cosas se estabilizan. Si una nueva actualización se activa mientras tu script aún se está ejecutando, la ejecución en vuelo se cancela. Si editas tu script, los cambios no aparecerán hasta que tu próxima interacción con Claude Code active una actualización.

Estos disparadores pueden quedarse en silencio cuando la sesión principal está inactiva, por ejemplo mientras un coordinador espera en subagentes de fondo. Para mantener segmentos basados en tiempo o de fuentes externas actuales durante períodos inactivos, establece refreshInterval para también volver a ejecutar el comando en un temporizador fijo.

Lo que tu script puede generar

• Múltiples líneas: cada declaración echo o print se muestra como una fila separada. Consulta el ejemplo de múltiples líneas.
• Colores: usa códigos de escape ANSI como \033[32m para verde (la terminal debe admitirlos). Consulta el ejemplo de estado de git.
• Enlaces: usa 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. Consulta el ejemplo de enlaces clickeables.

Datos disponibles

Claude Code envía los siguientes campos JSON a tu script a través de stdin:

{
"cwd": "/current/working/directory",
"session_id": "abc123...",
"session_name": "my-session",
"transcript_path": "/path/to/transcript.jsonl",
"model": {
"id": "claude-opus-4-7",
"display_name": "Opus"
},
"workspace": {
"current_dir": "/current/working/directory",
"project_dir": "/original/project/directory",
"added_dirs": [],
"git_worktree": "feature-xyz"
},
"version": "2.1.90",
"output_style": {
"name": "default"
},
"cost": {
"total_cost_usd": 0.01234,
"total_duration_ms": 45000,
"total_api_duration_ms": 2300,
"total_lines_added": 156,
"total_lines_removed": 23
},
"context_window": {
"total_input_tokens": 15500,
"total_output_tokens": 1200,
"context_window_size": 200000,
"used_percentage": 8,
"remaining_percentage": 92,
"current_usage": {
"input_tokens": 8500,
"output_tokens": 1200,
"cache_creation_input_tokens": 5000,
"cache_read_input_tokens": 2000
}
},
"exceeds_200k_tokens": false,
"effort": {
"level": "high"
},
"thinking": {
"enabled": true
},
"rate_limits": {
"five_hour": {
"used_percentage": 23.5,
"resets_at": 1738425600
},
"seven_day": {
"used_percentage": 41.2,
"resets_at": 1738857600
}
},
"vim": {
"mode": "NORMAL"
},
"agent": {
"name": "security-reviewer"
},
"worktree": {
"name": "my-feature",
"path": "/path/to/.claude/worktrees/my-feature",
"branch": "worktree-my-feature",
"original_cwd": "/path/to/project",
"original_branch": "main"
}
}

Campos de ventana de contexto

El objeto context_window describe la ventana de contexto en vivo de la respuesta de API más reciente. A partir de v2.1.132, total_input_tokens y total_output_tokens reflejan el uso actual del contexto, no totales acumulativos de sesión.

• Totales combinados (total_input_tokens, total_output_tokens): tokens actualmente en la ventana de contexto. total_input_tokens es la suma de input_tokens, cache_creation_input_tokens, y cache_read_input_tokens; total_output_tokens son los tokens de salida de la respuesta más reciente. Ambos son 0 antes 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.

El objeto current_usage contiene:

• input_tokens: tokens de entrada en contexto actual
• output_tokens: tokens de salida generados
• cache_creation_input_tokens: tokens escritos en caché
• cache_read_input_tokens: tokens leídos del caché

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

Ejemplos

Estos ejemplos muestran patrones comunes de línea de estado. Para usar cualquier ejemplo:

1. Guarda el script en un archivo como ~/.claude/statusline.sh (o .py/.js)
2. Hazlo ejecutable: chmod +x ~/.claude/statusline.sh
3. Agrega la ruta a tu configuración

Los ejemplos de Bash usan 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 campo used_percentage y construye una barra de 10 caracteres donde los bloques rellenos (▓) representan el uso:

#!/bin/bash
# Read all of stdin into a variable
input=$(cat)

# Extract fields with jq, "// 0" provides fallback for null
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Build progress bar: printf -v creates a run of spaces, then
# ${var// /▓} replaces each space with a block character
BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

echo "[$MODEL] $BAR $PCT%"

#!/usr/bin/env python3
import json, sys

# json.load reads and parses stdin in one step
data = json.load(sys.stdin)
model = data['model']['display_name']
# "or 0" handles null values
pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)

# String multiplication builds the bar
filled = pct * 10 // 100
bar = '▓' * filled + '░' * (10 - filled)

print(f"[{model}] {bar} {pct}%")

#!/usr/bin/env node
// Node.js reads stdin asynchronously with events
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
// Optional chaining (?.) safely handles null fields
const pct = Math.floor(data.context_window?.used_percentage || 0);

// String.repeat() builds the bar
const filled = Math.floor(pct * 10 / 100);
const bar = '▓'.repeat(filled) + '░'.repeat(10 - filled);

console.log(`[${model}] ${bar} ${pct}%`);
});

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.

Cada script verifica si el directorio actual es un repositorio de git, cuenta archivos preparados y modificados, y muestra indicadores codificados por colores:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')

GREEN='\033[32m'
YELLOW='\033[33m'
RESET='\033[0m'

if git rev-parse --git-dir > /dev/null 2>&1; then
BRANCH=$(git branch --show-current 2>/dev/null)
STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')

GIT_STATUS=""
[ "$STAGED" -gt 0 ] && GIT_STATUS="${GREEN}+${STAGED}${RESET}"
[ "$MODIFIED" -gt 0 ] && GIT_STATUS="${GIT_STATUS}${YELLOW}~${MODIFIED}${RESET}"

echo -e "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH $GIT_STATUS"
else
echo "[$MODEL] 📁 ${DIR##*/}"
fi

#!/usr/bin/env python3
import json, sys, subprocess, os

data = json.load(sys.stdin)
model = data['model']['display_name']
directory = os.path.basename(data['workspace']['current_dir'])

GREEN, YELLOW, RESET = '\033[32m', '\033[33m', '\033[0m'

try:
subprocess.check_output(['git', 'rev-parse', '--git-dir'], stderr=subprocess.DEVNULL)
branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True).strip()
staged_output = subprocess.check_output(['git', 'diff', '--cached', '--numstat'], text=True).strip()
modified_output = subprocess.check_output(['git', 'diff', '--numstat'], text=True).strip()
staged = len(staged_output.split('\n')) if staged_output else 0
modified = len(modified_output.split('\n')) if modified_output else 0

git_status = f"{GREEN}+{staged}{RESET}" if staged else ""
git_status += f"{YELLOW}~{modified}{RESET}" if modified else ""

print(f"[{model}] 📁 {directory} | 🌿 {branch} {git_status}")
except:
print(f"[{model}] 📁 {directory}")

#!/usr/bin/env node
const { execSync } = require('child_process');
const path = require('path');

let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const dir = path.basename(data.workspace.current_dir);

const GREEN = '\x1b[32m', YELLOW = '\x1b[33m', RESET = '\x1b[0m';

try {
execSync('git rev-parse --git-dir', { stdio: 'ignore' });
const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
const staged = execSync('git diff --cached --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
const modified = execSync('git diff --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;

let gitStatus = staged ? `${GREEN}+${staged}${RESET}` : '';
gitStatus += modified ? `${YELLOW}~${modified}${RESET}` : '';

console.log(`[${model}] 📁 ${dir} | 🌿 ${branch} ${gitStatus}`);
} catch {
console.log(`[${model}] 📁 ${dir}`);
}
});

Seguimiento de costos y duración

Rastrea los costos de API de tu sesión y el tiempo transcurrido. El campo cost.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:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

COST_FMT=$(printf '$%.2f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))

echo "[$MODEL] 💰 $COST_FMT | ⏱️ ${MINS}m ${SECS}s"

#!/usr/bin/env python3
import json, sys

data = json.load(sys.stdin)
model = data['model']['display_name']
cost = data.get('cost', {}).get('total_cost_usd', 0) or 0
duration_ms = data.get('cost', {}).get('total_duration_ms', 0) or 0

duration_sec = duration_ms // 1000
mins, secs = duration_sec // 60, duration_sec % 60

print(f"[{model}] 💰 ${cost:.2f} | ⏱️ {mins}m {secs}s")

#!/usr/bin/env node
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const cost = data.cost?.total_cost_usd || 0;
const durationMs = data.cost?.total_duration_ms || 0;

const durationSec = Math.floor(durationMs / 1000);
const mins = Math.floor(durationSec / 60);
const secs = durationSec % 60;

console.log(`[${model}] 💰 $${cost.toFixed(2)} | ⏱️ ${mins}m ${secs}s`);
});

Mostrar múltiples líneas

Tu script puede generar múltiples líneas para crear una pantalla más rica. Cada declaración echo produce una fila separada en el área de estado.

Este ejemplo combina varias técnicas: colores basados en umbrales (verde por debajo del 70%, amarillo 70-89%, rojo 90%+), una barra de progreso e información de rama de git. Cada declaración print o echo crea una fila separada:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

# Pick bar color based on context usage
if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"

MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))

BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | 🌿 $(git branch --show-current 2>/dev/null)"

echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
COST_FMT=$(printf '$%.2f' "$COST")
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"

#!/usr/bin/env python3
import json, sys, subprocess, os

data = json.load(sys.stdin)
model = data['model']['display_name']
directory = os.path.basename(data['workspace']['current_dir'])
cost = data.get('cost', {}).get('total_cost_usd', 0) or 0
pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)
duration_ms = data.get('cost', {}).get('total_duration_ms', 0) or 0

CYAN, GREEN, YELLOW, RED, RESET = '\033[36m', '\033[32m', '\033[33m', '\033[31m', '\033[0m'

bar_color = RED if pct >= 90 else YELLOW if pct >= 70 else GREEN
filled = pct // 10
bar = '█' * filled + '░' * (10 - filled)

mins, secs = duration_ms // 60000, (duration_ms % 60000) // 1000

try:
branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True, stderr=subprocess.DEVNULL).strip()
branch = f" | 🌿 {branch}" if branch else ""
except:
branch = ""

print(f"{CYAN}[{model}]{RESET} 📁 {directory}{branch}")
print(f"{bar_color}{bar}{RESET} {pct}% | {YELLOW}${cost:.2f}{RESET} | ⏱️ {mins}m {secs}s")

#!/usr/bin/env node
const { execSync } = require('child_process');
const path = require('path');

let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const dir = path.basename(data.workspace.current_dir);
const cost = data.cost?.total_cost_usd || 0;
const pct = Math.floor(data.context_window?.used_percentage || 0);
const durationMs = data.cost?.total_duration_ms || 0;

const CYAN = '\x1b[36m', GREEN = '\x1b[32m', YELLOW = '\x1b[33m', RED = '\x1b[31m', RESET = '\x1b[0m';

const barColor = pct >= 90 ? RED : pct >= 70 ? YELLOW : GREEN;
const filled = Math.floor(pct / 10);
const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);

const mins = Math.floor(durationMs / 60000);
const secs = Math.floor((durationMs % 60000) / 1000);

let branch = '';
try {
branch = execSync('git branch --show-current', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
branch = branch ? ` | 🌿 ${branch}` : '';
} catch {}

console.log(`${CYAN}[${model}]${RESET} 📁 ${dir}${branch}`);
console.log(`${barColor}${bar}${RESET} ${pct}% | ${YELLOW}$${cost.toFixed(2)}${RESET} | ⏱️ ${mins}m ${secs}s`);
});

Enlaces clickeables

Este ejemplo crea un enlace clickeable a tu repositorio de GitHub. Lee la URL remota de git, convierte el formato SSH a HTTPS con sed, y envuelve el nombre del repositorio en códigos de escape OSC 8. Mantén presionado Cmd (macOS) o Ctrl (Windows/Linux) y haz clic para abrir el enlace en tu navegador.

Cada script obtiene la URL remota de git, convierte el formato SSH a HTTPS, y envuelve el nombre del repositorio en códigos de escape OSC 8. La versión de Bash usa printf '%b' que interpreta escapes de barra invertida de manera más confiable que echo -e en diferentes shells:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')

# Convert git SSH URL to HTTPS
REMOTE=$(git remote get-url origin 2>/dev/null | sed 's/git@github.com:/https:\/\/github.com\//' | sed 's/\.git$//')

if [ -n "$REMOTE" ]; then
REPO_NAME=$(basename "$REMOTE")
# OSC 8 format: \e]8;;URL\a then TEXT then \e]8;;\a
# printf %b interprets escape sequences reliably across shells
printf '%b' "[$MODEL] 🔗 \e]8;;${REMOTE}\a${REPO_NAME}\e]8;;\a\n"
else
echo "[$MODEL]"
fi

#!/usr/bin/env python3
import json, sys, subprocess, re, os

data = json.load(sys.stdin)
model = data['model']['display_name']

# Get git remote URL
try:
remote = subprocess.check_output(
['git', 'remote', 'get-url', 'origin'],
stderr=subprocess.DEVNULL, text=True
).strip()
# Convert SSH to HTTPS format
remote = re.sub(r'^git@github\.com:', 'https://github.com/', remote)
remote = re.sub(r'\.git$', '', remote)
repo_name = os.path.basename(remote)
# OSC 8 escape sequences
link = f"\033]8;;{remote}\a{repo_name}\033]8;;\a"
print(f"[{model}] 🔗 {link}")
except:
print(f"[{model}]")

#!/usr/bin/env node
const { execSync } = require('child_process');
const path = require('path');

let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;

try {
let remote = execSync('git remote get-url origin', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
// Convert SSH to HTTPS format
remote = remote.replace(/^git@github\.com:/, 'https://github.com/').replace(/\.git$/, '');
const repoName = path.basename(remote);
// OSC 8 escape sequences
const link = `\x1b]8;;${remote}\x07${repoName}\x1b]8;;\x07`;
console.log(`[${model}] 🔗 ${link}`);
} catch {
console.log(`[${model}]`);
}
});

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 objeto rate_limits contiene five_hour (ventana móvil de 5 horas) y seven_day (ventanas semanales). Cada ventana proporciona used_percentage (0-100) y resets_at (segundos de época Unix cuando se reinicia la ventana).

Este campo solo está presente para suscriptores de Claude.ai (Pro/Max) después de la primera respuesta de API. Cada script maneja el campo ausente con elegancia:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
# "// empty" produces no output when rate_limits is absent
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

LIMITS=""
[ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"

[ -n "$LIMITS" ] && echo "[$MODEL] | $LIMITS" || echo "[$MODEL]"

#!/usr/bin/env python3
import json, sys

data = json.load(sys.stdin)
model = data['model']['display_name']

parts = []
rate = data.get('rate_limits', {})
five_h = rate.get('five_hour', {}).get('used_percentage')
week = rate.get('seven_day', {}).get('used_percentage')

if five_h is not None:
parts.append(f"5h: {five_h:.0f}%")
if week is not None:
parts.append(f"7d: {week:.0f}%")

if parts:
print(f"[{model}] | {' '.join(parts)}")
else:
print(f"[{model}]")

#!/usr/bin/env node
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;

const parts = [];
const fiveH = data.rate_limits?.five_hour?.used_percentage;
const week = data.rate_limits?.seven_day?.used_percentage;

if (fiveH != null) parts.push(`5h: ${Math.round(fiveH)}%`);
if (week != null) parts.push(`7d: ${Math.round(week)}%`);

console.log(parts.length ? `[${model}] | ${parts.join(' ')}` : `[${model}]`);
});

Cachear operaciones costosas

Tu script de línea de estado se ejecuta frecuentemente durante sesiones activas. Comandos como git 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:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
SESSION_ID=$(echo "$input" | jq -r '.session_id')

CACHE_FILE="/tmp/statusline-git-cache-$SESSION_ID"
CACHE_MAX_AGE=5  # seconds

cache_is_stale() {
[ ! -f "$CACHE_FILE" ] || \
# stat -f %m is macOS, stat -c %Y is Linux
[ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]
}

if cache_is_stale; then
if git rev-parse --git-dir > /dev/null 2>&1; then
BRANCH=$(git branch --show-current 2>/dev/null)
STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
else
echo "||" > "$CACHE_FILE"
fi
fi

IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"

if [ -n "$BRANCH" ]; then
echo "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH +$STAGED ~$MODIFIED"
else
echo "[$MODEL] 📁 ${DIR##*/}"
fi

#!/usr/bin/env python3
import json, sys, subprocess, os, time

data = json.load(sys.stdin)
model = data['model']['display_name']
directory = os.path.basename(data['workspace']['current_dir'])
session_id = data['session_id']

CACHE_FILE = f"/tmp/statusline-git-cache-{session_id}"
CACHE_MAX_AGE = 5  # seconds

def cache_is_stale():
if not os.path.exists(CACHE_FILE):
return True
return time.time() - os.path.getmtime(CACHE_FILE) > CACHE_MAX_AGE

if cache_is_stale():
try:
subprocess.check_output(['git', 'rev-parse', '--git-dir'], stderr=subprocess.DEVNULL)
branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True).strip()
staged = subprocess.check_output(['git', 'diff', '--cached', '--numstat'], text=True).strip()
modified = subprocess.check_output(['git', 'diff', '--numstat'], text=True).strip()
staged_count = len(staged.split('\n')) if staged else 0
modified_count = len(modified.split('\n')) if modified else 0
with open(CACHE_FILE, 'w') as f:
f.write(f"{branch}|{staged_count}|{modified_count}")
except:
with open(CACHE_FILE, 'w') as f:
f.write("||")

with open(CACHE_FILE) as f:
branch, staged, modified = f.read().strip().split('|')

if branch:
print(f"[{model}] 📁 {directory} | 🌿 {branch} +{staged} ~{modified}")
else:
print(f"[{model}] 📁 {directory}")

#!/usr/bin/env node
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const dir = path.basename(data.workspace.current_dir);
const sessionId = data.session_id;

const CACHE_FILE = `/tmp/statusline-git-cache-${sessionId}`;
const CACHE_MAX_AGE = 5; // seconds

const cacheIsStale = () => {
if (!fs.existsSync(CACHE_FILE)) return true;
return (Date.now() / 1000) - fs.statSync(CACHE_FILE).mtimeMs / 1000 > CACHE_MAX_AGE;
};

if (cacheIsStale()) {
try {
execSync('git rev-parse --git-dir', { stdio: 'ignore' });
const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
const staged = execSync('git diff --cached --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
const modified = execSync('git diff --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
fs.writeFileSync(CACHE_FILE, `${branch}|${staged}|${modified}`);
} catch {
fs.writeFileSync(CACHE_FILE, '||');
}
}

const [branch, staged, modified] = fs.readFileSync(CACHE_FILE, 'utf8').trim().split('|');

if (branch) {
console.log(`[${model}] 📁 ${dir} | 🌿 ${branch} +${staged} ~${modified}`);
} else {
console.log(`[${model}] 📁 ${dir}`);
}
});

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 como C:\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:

{
"statusLine": {
"type": "command",
"command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
}
}

$input_json = $input | Out-String | ConvertFrom-Json
$cwd = $input_json.cwd
$model = $input_json.model.display_name
$used = $input_json.context_window.used_percentage
$dirname = Split-Path $cwd -Leaf

if ($used) {
Write-Host "$dirname [$model] ctx: $used%"
} else {
Write-Host "$dirname [$model]"
}

O, cuando Git Bash está instalado, ejecuta un script de Bash directamente:

{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}

#!/usr/bin/env bash
input=$(cat)
cwd=$(echo "$input" | grep -o '"cwd":"[^"]*"' | cut -d'"' -f4)
model=$(echo "$input" | grep -o '"display_name":"[^"]*"' | cut -d'"' -f4)
dirname="${cwd##*[/\\]}"
echo "$dirname [$model]"

Líneas de estado de subagentes

La configuración subagentStatusLine 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.

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

El comando se ejecuta una vez por tick de actualización con todas las filas de subagentes visibles pasadas como un único objeto JSON en stdin. La entrada incluye los campos de hook base más columns (el ancho de fila utilizable) y un array tasks, donde cada tarea tiene id, name, type, status, description, label, startTime, tokenCount, tokenSamples, y cwd.

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 y disableAllHooks que se aplican a statusLine se aplican aquí. Los plugins pueden enviar una subagentStatusLine predeterminada en su settings.json.

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 status pueden causar retrasos. Consulta el ejemplo de caché para saber cómo manejar esto.

Proyectos comunitarios como ccstatusline y starship-claude proporcionan configuraciones preconstruidas con temas y características adicionales.

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 command se consuman como caracteres de escape antes de que se ejecute el script. Usa barras diagonales en la ruta. Consulta Configuración de Windows.
• Si disableAllHooks está establecido en true en tu configuración, la línea de estado también está deshabilitada. Elimina esta configuración o establécela en false para volver a habilitarla.
• Ejecuta claude --debug para registrar el código de salida y stderr de la primera invocación de línea de estado en una sesión
• Pídele a Claude que lea tu archivo de configuración y ejecute el comando statusLine directamente para exponer errores

La línea de estado muestra -- o valores vacíos

• Los campos pueden ser null antes de que se complete la primera respuesta de API
• Maneja valores nulos en tu script con valores predeterminados de respaldo como // 0 en jq
• Reinicia Claude Code si los valores permanecen vacíos después de múltiples mensajes

El porcentaje de contexto muestra valores inesperados

• Usa used_percentage para el estado de contexto más simple y preciso
• El porcentaje de contexto puede diferir de la salida /context debido a cuándo se calcula cada uno

Los enlaces OSC 8 no son clickeables

• 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. Esto afecta comúnmente a Windows Terminal y otros emuladores no en la lista de detección automática. Establece la variable de entorno FORCE_HYPERLINK para anular la detección antes de lanzar Claude Code:

  FORCE_HYPERLINK=1 claude
  

  En PowerShell, establece la variable en la sesión actual primero:

  $env:FORCE_HYPERLINK = "1"; claude
  

• 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;;, usa printf '%b' en lugar de echo -e para un manejo más confiable de escapes

Problemas de visualización con secuencias de escape

• 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

Confianza del espacio de trabajo requerida

• El comando de línea de estado solo se ejecuta si has aceptado el diálogo de confianza del espacio de trabajo para el directorio actual. Debido a que statusLine ejecuta un comando de shell, requiere la misma aceptación de confianza que hooks y otras configuraciones que ejecutan shell.
• Si la confianza no se acepta, verás la notificación statusline skipped · restart to fix en lugar de tu salida de línea de estado. Reinicia Claude Code y acepta el mensaje de confianza para habilitarlo.

Errores de script o bloqueos

• 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 comparten la fila de la línea de estado

• Las notificaciones del sistema como errores de servidor MCP y actualizaciones automáticas se muestran en el lado derecho de la misma fila que tu línea de estado. 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