- 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
esc per interrompere, il fallback ? per scorciatoie e il suggerimento tieni premuto spazio per parlare della dettatura vocale. Per aggiungere badge di collegamento cliccabili al footer quando un ID appare nella conversazione, senza scrivere uno script, configura invece footerLinksRegexes.
Ecco un esempio di una barra di stato multi-riga che visualizza le informazioni git sulla prima riga e una barra di contesto codificata a colori sulla seconda.

Configura una barra di stato
Usa il comando/statusline per far generare uno script a Claude Code, oppure crea manualmente uno script e aggiungilo alle tue impostazioni.
Usa il comando /statusline
Il comando/statusline accetta istruzioni in linguaggio naturale che descrivono cosa vuoi visualizzare. Claude Code genera un file di script in ~/.claude/ e aggiorna automaticamente le tue impostazioni:
Configura manualmente una barra di stato
Aggiungi un campostatusLine alle tue impostazioni utente (~/.claude/settings.json, dove ~ è la tua directory home) o alle impostazioni del progetto. Imposta type su "command" e punta command a un percorso di script o a un comando di shell inline. Per una procedura dettagliata sulla creazione di uno script, vedi Costruisci una barra di stato passo dopo passo.
command viene eseguito in una shell, quindi puoi anche usare comandi inline invece di un file di script. Questo esempio usa jq per analizzare l’input JSON e visualizzare il nome del modello e la percentuale di contesto:
padding aggiunge spazi orizzontali extra (in caratteri) al contenuto della barra di stato. Il valore predefinito è 0. Questo padding è in aggiunta alla spaziatura integrata dell’interfaccia, quindi controlla l’indentazione relativa piuttosto che la distanza assoluta dal bordo del terminale.
Il campo opzionale refreshInterval esegue nuovamente il tuo comando ogni N secondi oltre agli aggiornamenti guidati da eventi. Il minimo è 1. Impostalo quando la tua barra di stato mostra dati basati sul tempo come un orologio, o quando i subagent in background cambiano lo stato git mentre la sessione principale è inattiva. Lascialo non impostato per eseguire solo su eventi.
Il campo opzionale hideVimModeIndicator sopprime il testo integrato -- INSERT -- sotto il prompt. Impostalo su true quando il tuo script renderizza vim.mode stesso, in modo che la modalità non venga visualizzata due volte.
Disabilita la barra di stato
Esegui/statusline e chiedigli di rimuovere o cancellare la tua barra di stato (ad esempio, /statusline delete, /statusline clear, /statusline remove it). Puoi anche eliminare manualmente il campo statusLine dal tuo settings.json.
Costruisci una barra di stato passo dopo passo
Questa procedura mostra cosa sta accadendo dietro le quinte creando manualmente una barra di stato che visualizza il modello corrente, la directory di lavoro e la percentuale di utilizzo della finestra di contesto.Eseguire
/statusline con una descrizione di quello che vuoi configura tutto questo automaticamente per te.
1
Crea uno script che legge JSON e stampa l'output
Claude Code invia dati JSON al tuo script tramite stdin. Questo script usa
jq, un parser JSON da riga di comando che potrebbe essere necessario installare, per estrarre il nome del modello, la directory e la percentuale di contesto, quindi stampa una riga formattata.Salva questo in ~/.claude/statusline.sh (dove ~ è la tua directory home, come /Users/username su macOS o /home/username su Linux):2
Rendilo eseguibile
Contrassegna lo script come eseguibile in modo che la tua shell possa eseguirlo:
3
Aggiungi alle impostazioni
Dì a Claude Code di eseguire il tuo script come barra di stato. Aggiungi questa configurazione a La tua barra di stato appare nella parte inferiore dell’interfaccia. Claude Code ricarica automaticamente le impostazioni ed esegue il tuo script non appena salvi il file.
~/.claude/settings.json, che imposta type su "command" (che significa “esegui questo comando di shell”) e punta command al tuo script:Come funzionano le barre di stato
Claude Code esegue il tuo script con dati di sessione JSON su stdin e visualizza tutto ciò che lo script stampa su stdout. Quando si aggiorna Il tuo script viene eseguito una volta quando una sessione inizia, incluso quando ne riprendi una. Dopo di che, viene eseguito di nuovo quando:- Arriva un nuovo messaggio dell’assistente
/compacttermina- La modalità di autorizzazione cambia
- La modalità Vim si attiva/disattiva
- Cambi il
commandnelle tue impostazionistatusLine - Un timer
refreshIntervalscade, se ne hai impostato uno - Una finestra di rate-limit nei dati che il tuo script ha ricevuto per ultimo raggiunge il suo tempo
resets_at - Una prompt cache calda nei dati che il tuo script ha ricevuto per ultimo raggiunge il suo tempo
expires_at
command stesso salta il debounce: Claude Code esegue il nuovo comando subito. Se un nuovo aggiornamento si attiva mentre il tuo script è ancora in esecuzione, Claude Code annulla lo script in corso. Se modifichi il tuo script, le modifiche appariranno la prossima volta che un trigger di aggiornamento lo riesegue.
I trigger guidati dagli eventi possono diventare silenziosi quando la sessione principale è inattiva, ad esempio mentre un coordinatore attende i subagent in background. Per mantenere i segmenti basati sul tempo o provenienti da fonti esterne aggiornati durante i periodi di inattività, imposta refreshInterval per eseguire nuovamente il comando anche su un timer fisso.
Cosa può produrre il tuo script
- Più righe: ogni istruzione
echooprintviene visualizzata come una riga separata. Vedi l’esempio multi-riga. - Colori: usa codici di escape ANSI come
\033[32mper 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.
tput cols e il rilevamento della larghezza a livello di linguaggio non possono leggere la dimensione del terminale dall’interno dello script. Leggi invece le variabili di ambiente COLUMNS e LINES. Claude Code imposta queste variabili alle dimensioni attuali del terminale prima di eseguire il tuo script.
La barra di stato viene eseguita localmente e non consuma token API. Si nasconde temporaneamente durante determinate interazioni dell’interfaccia utente, inclusi i suggerimenti di completamento automatico, il menu della guida e i prompt di autorizzazione.
Dati disponibili
Claude Code invia i seguenti campi JSON al tuo script tramite stdin:Schema JSON completo
Schema JSON completo
Il tuo comando della barra di stato riceve questa struttura JSON tramite stdin:Campi che potrebbero essere assenti (non presenti in JSON):
session_name: appare quando un nome personalizzato è stato impostato con--nameo/rename, o una volta che esiste un titolo di sessione generato dall’IA. Il nome visualizzato predefinito, comemy-app-3f, non lo popolaprompt_id: appare solo dopo il primo input dell’utenteworkspace.git_worktree: appare solo quando la directory corrente si trova all’interno di un git worktree collegatoworkspace.repo: appare solo all’interno di un repository git con un remoteoriginconfiguratoeffort: appare solo quando il modello corrente supporta il parametro di sforzo di ragionamentovim: appare solo quando la modalità vim è abilitataagent: appare solo quando si esegue con il flag--agento le impostazioni dell’agente configuratepr: appare solo mentre viene trovata una PR aperta o una merge request GitLab per il ramo corrente, e viene rimossa una volta che si unisce o si chiude.pr.review_stateepr.kindpotrebbero essere indipendentemente assentiworktree: appare solo durante una sessione worktree. Quando presente,brancheoriginal_branchpotrebbero anche essere assenti per i worktree basati su hookrate_limits: appare solo per gli abbonati Claude.ai Pro e Max, o dietro un gateway di app Claude che imposta un limite di spesa per te, e solo dopo la prima risposta API nella sessione. Ogni finestra (five_hour,seven_day,spend_limit) potrebbe essere indipendentemente assente, e Claude Code elimina una finestra una volta che il suo temporesets_atpassa. Usajq -r '.rate_limits.five_hour.used_percentage // empty'per gestire l’assenza con eleganza.prompt_cache: appare dopo la prima risposta API della conversazione principale. Vedi campi della prompt cache
null:context_window.current_usage:nullprima della prima chiamata API in una sessione, e di nuovo dopo/compactfino a quando la prossima chiamata API non lo ripopolacontext_window.used_percentage,context_window.remaining_percentage: potrebbero esserenullall’inizio della sessione
Campi della finestra di contesto
L’oggettocontext_window descrive la finestra di contesto attiva dalla risposta API più recente.
- Totali combinati (
total_input_tokens,total_output_tokens): token attualmente nella finestra di contesto.total_input_tokensè la somma diinput_tokens,cache_creation_input_tokensecache_read_input_tokens;total_output_tokenssono i token di output dalla risposta più recente. Entrambi sono0prima 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.
current_usage contiene:
input_tokens: token di input nel contesto correnteoutput_tokens: token di output generaticache_creation_input_tokens: token scritti nella cachecache_read_input_tokens: token letti dalla cache
used_percentage viene calcolato solo dai token di input: input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Non include output_tokens.
Se calcoli manualmente la percentuale di contesto da current_usage, usa la stessa formula solo per l’input per corrispondere a used_percentage.
L’oggetto current_usage è null prima della prima chiamata API in una sessione, e di nuovo immediatamente dopo /compact fino a quando la prossima chiamata API non lo ripopola.
Campi della prompt cache
L’oggettoprompt_cache riassume come la conversazione principale della sessione sta utilizzando la prompt cache. Claude Code la calcola dai conteggi dei token della cache nelle risposte dell’API, quindi funziona su ogni provider.
L’oggetto appare dopo la prima risposta API della conversazione principale. Claude Code non conta le richieste dei subagent in queste statistiche. Richiede Claude Code v2.1.251 o successivo.
La tabella elenca ogni campo con il suo significato. I timestamp sono secondi di epoca Unix, la stessa unità di rate_limits.*.resets_at. Una barra di stato breve di solito mostra uno o due di questi; warm e hit_ratio riassumono lo stato della cache più direttamente.
Claude Code mostra le stesse statistiche nel terminale, sulla riga
/usage della Prompt cache (main).
Causa dell’ultima mancanza
L’oggettolast_miss_cause segnala quello che Claude Code ha identificato come la probabile causa della mancanza più recente. Il suo array causes contiene uno o più nomi di causa, come tools_changed, system_prompt_changed, ttl_expired_5m, o likely_server_side. L’oggetto è null fino alla prima mancanza della sessione, e di nuovo ogni volta che Claude Code non riesce a identificare una causa per la mancanza più recente. Richiede Claude Code v2.1.260 o successivo.
Due cause aggiungono conteggi all’oggetto:
tools_addedetools_removed: contools_changed, quanti strumenti sono stati aggiunti o rimossi dalla richiestasystem_char_delta: consystem_prompt_changed, il cambiamento nella lunghezza del prompt di sistema, in caratteri
Esempi
Questi esempi mostrano modelli comuni della barra di stato. Per usare qualsiasi esempio:- Salva lo script in un file come
~/.claude/statusline.sh(o.py/.js) - Rendilo eseguibile:
chmod +x ~/.claude/statusline.sh - Aggiungi il percorso alle tue impostazioni
jq per analizzare JSON. Python e Node.js hanno l’analisi JSON integrata.
Utilizzo della finestra di contesto
Visualizza il modello corrente e l’utilizzo della finestra di contesto con una barra di progresso visiva. Ogni script legge JSON da stdin, estrae il campoused_percentage e costruisce una barra di 10 caratteri dove i blocchi pieni (▓) rappresentano l’utilizzo:

Stato git con colori
Mostra il ramo git con indicatori codificati a colori per i file in staging e modificati. Questo script usa codici di escape ANSI per i colori del terminale:\033[32m è verde, \033[33m è giallo e \033[0m ripristina il valore predefinito.

Tracciamento di costi e durata
Traccia i costi API della tua sessione e il tempo trascorso. Il campocost.total_cost_usd accumula il costo stimato di tutte le chiamate API nella sessione corrente. Il campo cost.total_duration_ms misura il tempo totale trascorso dall’inizio della sessione, mentre cost.total_api_duration_ms traccia solo il tempo trascorso in attesa delle risposte API.
Ogni script formatta il costo come valuta e converte i millisecondi in minuti e secondi:

Visualizza più righe
Il tuo script può produrre più righe per creare una visualizzazione più ricca.
print o echo crea una riga separata:
Link cliccabili
Questo esempio crea un link cliccabile al tuo repository GitHub. Tieni premuto Cmd (macOS) o Ctrl (Windows/Linux) e fai clic per aprire il link nel tuo browser.
printf '%b' che interpreta gli escape di backslash in modo più affidabile rispetto a echo -e su diverse shell:
Utilizzo del limite di velocità
Visualizza l’utilizzo del limite di velocità dell’abbonamento Claude.ai nella barra di stato. L’oggettorate_limits contiene una finestra mobile five_hour e una finestra settimanale seven_day. Ogni finestra fornisce used_percentage, da 0 a 100, e resets_at, i secondi di epoca Unix quando la finestra si ripristina.
Dietro un gateway di app Claude con limiti di spesa, rate_limits contiene spend_limit con gli stessi due campi per il limite di spesa che si applica a te, tranne che il suo used_percentage può superare 100 una volta che superi il limite. Richiede Claude Code v2.1.251 o successivo.
L’oggetto rate_limits è presente solo per gli abbonati Claude.ai Pro e Max, o dietro un gateway di app Claude con limiti di spesa, e solo dopo la prima risposta API. Ogni script gestisce il campo assente con eleganza:
Memorizza nella cache le operazioni costose
Il tuo script della barra di stato viene eseguito frequentemente durante le sessioni attive. Comandi comegit status o git diff possono essere lenti, specialmente in repository di grandi dimensioni. Questo esempio memorizza nella cache le informazioni git in un file temporaneo e le aggiorna solo ogni 5 secondi.
Il nome del file di cache deve essere stabile tra le invocazioni della barra di stato all’interno di una sessione, ma univoco tra le sessioni in modo che le sessioni simultanee in repository diversi non leggano lo stato git memorizzato nella cache l’uno dell’altro. Gli identificatori basati su processi come $$, os.getpid() o process.pid cambiano ad ogni invocazione e annullano la cache. Usa invece session_id dall’input JSON: è stabile per la durata di una sessione ed è univoco per sessione.
Ogni script verifica se il file di cache è mancante o più vecchio di 5 secondi prima di eseguire i comandi git:
Configurazione Windows
Su Windows, Claude Code esegue i comandi della barra di stato tramite Git Bash quando Git Bash è installato, o tramite PowerShell quando Git Bash è assente. Git Bash tratta i backslash non quotati come caratteri di escape, quindi un percorso in stile Windows comeC:\Users\username\script.mjs raggiunge lo script runner con i suoi separatori rimossi e il comando fallisce senza un errore visibile. Scrivi i percorsi dei file nella stringa command con barre oblique, come mostrato negli esempi seguenti. La scorciatoia ~ funziona anche e si espande alla tua directory home di Windows.
Per eseguire uno script PowerShell come barra di stato, invocalo tramite powershell. Questo funziona indipendentemente dal fatto che Claude Code instrada il comando tramite Git Bash o PowerShell:
Barre di stato dei subagent
L’impostazionesubagentStatusLine renderizza un corpo di riga personalizzato per ogni subagent mostrato nel pannello dell’agente sotto il prompt. Usalo per sostituire la riga predefinita name · description · token count con la tua formattazione.
columns con la larghezza di riga utilizzabile, e un array tasks. Ogni task ha id, name, type, status, description, label, startTime, model, effort, contextWindowSize, tokenCount, tokenSamples e cwd.
Il campo model per-task è l’ID del modello risolto su cui viene eseguito il task. contextWindowSize è la finestra di contesto di quel modello in token, calcolata nello stesso modo della barra di stato principale context_window.context_window_size, quindi puoi renderizzare una percentuale per-riga da tokenCount. Entrambi i campi richiedono Claude Code v2.1.205 o successivo e vengono omessi per un task il cui modello non è ancora risolto.
Il campo effort per-task è lo sforzo di ragionamento impostato per quel subagent, nella sua frontmatter di definizione o nell’invocazione individuale. Il valore è uno dei livelli di sforzo low, medium, high, xhigh o max, oppure un budget di token numerico. Il campo riporta il valore configurato così come scritto: se il modello non supporta quel livello, lo sforzo che Claude Code applica effettivamente potrebbe essere diverso. Il campo richiede Claude Code v2.1.214 o successivo ed è assente quando il subagent eredita il livello di sforzo della sessione.
Scrivi una riga JSON su stdout per ogni riga che vuoi sovrascrivere, nella forma {"id": "<task id>", "content": "<row body>"}. La stringa content viene renderizzata così com’è, inclusi i colori ANSI e i hyperlink OSC 8. Ometti l’id di un task per mantenere il rendering predefinito per quella riga; emetti una stringa content vuota per nasconderla.
Gli stessi gate di fiducia, disableAllHooks e allowManagedHooksOnly che si applicano a statusLine si applicano qui. I plugin possono fornire un subagentStatusLine predefinito nel loro settings.json, ma a differenza dei hooks, i valori dei plugin non vengono eseguiti sotto allowManagedHooksOnly anche quando il plugin è forzato abilitato nelle impostazioni gestite enabledPlugins.
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 statuspossono causare lag. Vedi l’esempio di caching per come gestire questo.
Risoluzione dei problemi
La barra di stato non appare- 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
- Su Windows con Git Bash installato, i backslash nel percorso
commandvengono probabilmente consumati come caratteri di escape prima che lo script venga eseguito. Usa barre oblique nel percorso. Vedi Configurazione Windows. - Se
disableAllHooksètrueal di fuori delle impostazioni gestite dopo che la precedenza delle impostazioni si applica, Claude Code esegue solo unostatusLinedalle impostazioni gestite, e senza unostatusLinegestito la barra di stato è disabilitata. Rimuovi l’impostazione, o impostala sufalsenel file che la imposta, per riabilitarla. VedidisableAllHooks. - Se la tua organizzazione imposta
allowManagedHooksOnlynelle impostazioni gestite, la tua barra di stato personalizzata scompare senza avviso: puoi ottenere una barra di stato solo da un valorestatusLinein quelle impostazioni gestite. Vedi cosa viene eseguito sottoallowManagedHooksOnlyper il comportamento completo, e chiedi al tuo amministratore se questa impostazione si applica a te. - Esegui
claude --debugper 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
statusLinedirettamente per far emergere gli errori
-- o valori vuoti
- I campi potrebbero essere
nullprima che la prima risposta API si completi - Gestisci i valori null nel tuo script con fallback come
// 0in jq - Riavvia Claude Code se i valori rimangono vuoti dopo più messaggi
- Usa
used_percentageper lo stato di contesto più semplice e accurato - La percentuale di contesto potrebbe differire dall’output
/contexta 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. Imposta la variabile di ambiente
FORCE_HYPERLINKper sovrascrivere il rilevamento prima di avviare Claude Code:In PowerShell, imposta la variabile nella sessione corrente prima: - 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;;, usaprintf '%b'invece diecho -eper 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
- Poiché
statusLineesegue un comando di shell, Claude Code lo esegue secondo la stessa regola di fiducia dell’area di lavoro degli hook nei file di impostazioni. Accettare la finestra di dialogo per la cartella, o per una directory padre la cui fiducia si estende ad essa, è sufficiente. - Fino ad allora, la barra di stato rimane vuota, e
claude --debugregistraStatus line command skipped: workspace trust not accepted. Riavvia Claude Code e accetta la finestra di dialogo 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 riga. 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