Personalizza la tua barra di stato

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

• Vuoi monitorare l’utilizzo della finestra di contesto mentre lavori
• Hai bisogno di tracciare i costi della sessione
• Lavori su più sessioni e hai bisogno di distinguerle
• Vuoi che il ramo git e lo stato siano sempre visibili

​

Configura una barra di stato

​

Usa il comando /statusline

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

​

Configura manualmente una barra di stato

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

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

​

Disabilita la barra di stato

​

Costruisci una barra di stato passo dopo passo

#!/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"
  }
}

​

Come funzionano le barre di stato

• Più righe: ogni istruzione echo o print viene visualizzata come una riga separata. Vedi l’esempio multi-riga.
• Colori: usa codici di escape ANSI come \033[32m per il verde (il terminale deve supportarli). Vedi l’esempio di stato git.
• Link: usa sequenze di escape OSC 8 per rendere il testo cliccabile (Cmd+clic su macOS, Ctrl+clic su Windows/Linux). Richiede un terminale che supporti i hyperlink come iTerm2, Kitty o WezTerm. Vedi l’esempio di link cliccabili.

​

Dati disponibili

{
  "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"
  }
}

​

Campi della finestra di contesto

• Totali combinati (total_input_tokens, total_output_tokens): token attualmente nella finestra di contesto. total_input_tokens è la somma di input_tokens, cache_creation_input_tokens e cache_read_input_tokens; total_output_tokens sono i token di output dalla risposta più recente. Entrambi sono 0 prima della prima risposta API.
• Utilizzo per componente (current_usage): gli stessi conteggi dei token suddivisi per categoria. Usa questo quando hai bisogno di separare i cache hit dall’input fresco.

• input_tokens: token di input nel contesto corrente
• output_tokens: token di output generati
• cache_creation_input_tokens: token scritti nella cache
• cache_read_input_tokens: token letti dalla cache

​

Esempi

1. Salva lo script in un file come ~/.claude/statusline.sh (o .py/.js)
2. Rendilo eseguibile: chmod +x ~/.claude/statusline.sh
3. Aggiungi il percorso alle tue impostazioni

​

Utilizzo della finestra di contesto

#!/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%"

​

Stato git con colori

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

​

Tracciamento di costi e durata

#!/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"

​

Visualizza più righe

#!/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"

​

Link cliccabili

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

​

Utilizzo del limite di velocità

#!/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]"

​

Memorizza nella cache le operazioni costose

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

​

Configurazione Windows

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

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

​

Barre di stato dei subagent

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

​

Suggerimenti

• Testa con input simulato: echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh
• Mantieni l’output breve: la barra di stato ha una larghezza limitata, quindi l’output lungo potrebbe essere troncato o andare a capo in modo sgradevole
• Memorizza nella cache le operazioni lente: il tuo script viene eseguito frequentemente durante le sessioni attive, quindi comandi come git status possono causare lag. Vedi l’esempio di caching per come gestire questo.

​

Risoluzione dei problemi

• Verifica che il tuo script sia eseguibile: chmod +x ~/.claude/statusline.sh
• Controlla che il tuo script stampi su stdout, non su stderr
• Esegui il tuo script manualmente per verificare che produca output
• Se disableAllHooks è impostato su true nelle tue impostazioni, anche la barra di stato è disabilitata. Rimuovi questa impostazione o impostala su false per riabilitarla.
• Esegui claude --debug per registrare il codice di uscita e stderr dalla prima invocazione della barra di stato in una sessione
• Chiedi a Claude di leggere il tuo file di impostazioni ed eseguire il comando statusLine direttamente per far emergere gli errori

• I campi potrebbero essere null prima che la prima risposta API si completi
• Gestisci i valori null nel tuo script con fallback come // 0 in jq
• Riavvia Claude Code se i valori rimangono vuoti dopo più messaggi

• Usa used_percentage per lo stato di contesto più semplice e accurato
• La percentuale di contesto potrebbe differire dall’output /context a causa di quando ciascuno viene calcolato

• Verifica che il tuo terminale supporti i hyperlink OSC 8 (iTerm2, Kitty, WezTerm)
• Terminal.app non supporta i link cliccabili
• Se il testo del link appare ma non è cliccabile, Claude Code potrebbe non aver rilevato il supporto dei hyperlink nel tuo terminale. Questo accade comunemente con Windows Terminal e altri emulatori non nell’elenco di rilevamento automatico. Imposta la variabile di ambiente FORCE_HYPERLINK per sovrascrivere il rilevamento prima di avviare Claude Code:
  FORCE_HYPERLINK=1 claude
  
  In PowerShell, imposta la variabile nella sessione corrente prima:
  $env:FORCE_HYPERLINK = "1"; claude
  
• Le sessioni SSH e tmux potrebbero eliminare le sequenze OSC a seconda della configurazione
• Se le sequenze di escape appaiono come testo letterale come \e]8;;, usa printf '%b' invece di echo -e per una gestione più affidabile degli escape

• Le sequenze di escape complesse (colori ANSI, link OSC 8) possono occasionalmente causare output corrotto se si sovrappongono ad altri aggiornamenti dell’interfaccia utente
• Se vedi testo corrotto, prova a semplificare il tuo script in output di testo semplice
• Le barre di stato multi-riga con codici di escape sono più soggette a problemi di rendering rispetto al testo semplice su una sola riga

• Il comando della barra di stato viene eseguito solo se hai accettato la finestra di dialogo di fiducia dell’area di lavoro per la directory corrente. Poiché statusLine esegue un comando di shell, richiede la stessa accettazione di fiducia di hook e altre impostazioni che eseguono shell.
• Se la fiducia non è accettata, vedrai la notifica statusline skipped · restart to fix invece dell’output della tua barra di stato. Riavvia Claude Code e accetta il prompt di fiducia per abilitarla.

• Gli script che escono con codici diversi da zero o non producono output causano il vuoto della barra di stato
• Gli script lenti bloccano l’aggiornamento della barra di stato fino al completamento. Mantieni gli script veloci per evitare output obsoleto.
• Se un nuovo aggiornamento si attiva mentre uno script lento è in esecuzione, lo script in corso viene annullato
• Testa il tuo script indipendentemente con input simulato prima di configurarlo

• Le notifiche di sistema come errori del server MCP e aggiornamenti automatici vengono visualizzate sul lato destro della stessa riga della tua barra di stato. Le notifiche transitorie come l’avviso di contesto basso si cicla anche attraverso questa area.
• L’abilitazione della modalità verbose aggiunge un contatore di token a questa area
• Su terminali stretti, queste notifiche potrebbero troncare l’output della tua barra di stato