Come creare una status line utile in Claude Code

Una status line di Claude Code può mostrarti, durante il lavoro, il progetto corrente, il branch, l'uso del contesto e una stima del costo della sessione. È utile quando questi segnali cambiano una decisione: fermarti prima di lavorare nel repository sbagliato, compattare con criterio, chiudere un task o controllare un'anomalia.

La barra diventa rumore quando accumula numeri senza una risposta prevista. Prima di configurarla, decidi che cosa farai se un valore cambia. Poi crea uno script piccolo, provalo con un input controllato e verifica che non rallenti l'interfaccia. L'obiettivo non è vedere tutto: è accorgerti in tempo di ciò che richiede un'azione.

Una status line è utile soltanto se cambia una decisione

Claude Code invia allo script un oggetto JSON con dati della sessione. Lo script seleziona alcuni campi, li formatta e scrive una riga o più righe. La status line non interpreta il lavoro al posto tuo: rende persistenti segnali che altrimenti dovresti cercare in comandi o menu separati.

Per ogni dato candidato, completa la frase: “Se questo valore cambia, io…”.

• Se il branch non è quello atteso, fermo le modifiche e verifico la directory.

• Se il contesto diventa troppo affollato per il task, salvo lo stato e valuto una compaction mirata.

• Se la stima cresce in modo inatteso, controllo che la sessione non stia rileggendo file inutili.

• Se la directory cambia, verifico che lo scope autorizzato sia ancora corretto.

Se non sai completare la frase, il dato probabilmente non merita spazio. Una barra corta letta davvero vale più di una dashboard che diventa sfondo.

Scegli quattro segnali minimi

Per iniziare bastano quattro famiglie di segnali.

La documentazione offre molti altri campi: modello, effort, righe aggiunte e rimosse, tempo di risposta, directory aggiunte. Aggiungili soltanto quando esiste un caso d'uso. Se cambi spesso effort nella stessa sessione, può essere utile visualizzarlo; se non lo cambi mai, occupa spazio senza ridurre un rischio.

Evita dati sensibili. Un percorso completo può contenere un nome personale o cliente. In un terminale condiviso o in uno screenshot, mostra soltanto il segmento necessario a distinguere il progetto.

Collega ogni segnale a un'azione

Costruisci una matrice con quattro colonne: Segnale, Soglia, Azione, Prova.

La soglia non deve essere per forza numerica. Per il branch può essere “diverso da quello dichiarato nel task”. Per la directory può essere “fuori dalla root del progetto”. Per il contesto, definisci una fascia che per il tuo modo di lavorare richiede una verifica; non esiste una percentuale universale che ordini di compattare.

La prova descrive come saprai che l'azione ha funzionato:

• dopo il cambio di branch, la barra mostra il nome atteso;

• dopo /compact, il contesto scende e le istruzioni permanenti restano disponibili;

• dopo aver ristretto lo scope, la stima smette di crescere allo stesso ritmo;

• dopo una nuova sessione, directory e task coincidono.

Questa struttura evita allarmi cosmetici. Rosso, giallo e verde hanno senso soltanto se corrispondono a comportamenti diversi. Non colorare un valore perché “sembra alto”: prima definisci la conseguenza.

Genera la configurazione senza nascondere lo script

Il comando /statusline accetta una richiesta in linguaggio naturale e può generare script e configurazione. Puoi partire, per esempio, da:

/statusline mostra nome breve del progetto, branch o worktree,
percentuale di contesto usato e costo stimato della sessione.
Gestisci i valori mancanti con un trattino e usa una sola riga.

Dopo la generazione, apri lo script. Verifica quali campi legge, quali comandi esegue e dove si trova. La status line viene eseguita localmente: non trattare il codice generato come un dettaglio invisibile. Se chiama git status o altri comandi, controlla che siano rapidi e limitati al repository previsto.

La configurazione manuale usa una voce statusLine nelle impostazioni utente o di progetto e indica un comando. La scelta dello scope conta: una barra personale può stare nelle impostazioni utente; una configurazione condivisa deve funzionare su macchine diverse e non includere percorsi assoluti personali.

Prima di versionare uno script per il team, documenta dipendenze come jq, comportamento su Windows e output atteso. Una configurazione che funziona soltanto sulla macchina dell'autore non è ancora un artefatto condivisibile.

Gestisci stime, null e aggiornamenti

Il campo del costo è una stima client-side. Usalo per rilevare un andamento o un'anomalia, non per riconciliare una fattura. Evita testi come “spesa esatta” e preferisci stima sessione.

All'inizio della sessione alcuni valori possono essere nulli perché non è ancora arrivata una risposta del modello. Lo script deve mostrare un fallback leggibile invece di fallire. Anche la percentuale di contesto può aggiornarsi in momenti diversi rispetto ad altre viste; per una barra operativa usa il campo pre-calcolato indicato dalla documentazione e non ricostruire una formula con contatori incompatibili.

La status line si aggiorna dopo eventi della sessione e può avere un intervallo aggiuntivo. Un refresh troppo frequente non rende più accurato un dato che cambia soltanto dopo una risposta. Se inserisci l'ora o uno stato esterno, valuta un intervallo; altrimenti lascia gli aggiornamenti guidati dagli eventi.

Se lo script impiega troppo tempo, la barra resta indietro o l'esecuzione viene annullata da un nuovo aggiornamento. Mantieni l'elaborazione locale, breve e prevedibile. Operazioni di rete non appartengono a una status line minima.

Prova lo script con un input finto

Non aspettare una sessione costosa per scoprire che la barra mostra il branch sbagliato. Prepara un JSON minimo con i campi che usi e passalo allo script su stdin. La documentazione ufficiale propone proprio questo tipo di prova.

Definisci almeno quattro casi:

1. tutti i campi presenti;

2. costo o contesto nulli;

3. directory con spazi;

4. worktree assente o presente.

Per ogni caso scrivi l'output atteso. Il test non deve verificare soltanto che lo script “stampi qualcosa”: confronta etichette, fallback, ordine e assenza di dati sensibili. Se usi colori, controlla anche una modalità senza colore per log e terminali non compatibili.

Poi avvia una sessione reale in un progetto di prova. Cambia directory o branch in modo controllato, invia una richiesta breve e verifica che la barra reagisca. Il passaggio dal fixture alla sessione scopre differenze di shell, trust e permessi.

Rivedi la barra dopo una settimana di lavoro

Dopo un periodo d'uso, chiediti quali segnali hai davvero consultato. Se una voce non ha mai prodotto un'azione, rimuovila o riscrivi il contratto. Se hai aperto spesso altri menu per controllare un dato assente, valuta di aggiungerlo.

Non trasformare la status line in memoria di progetto. Convenzioni, procedure e decisioni restano nei file appropriati; la barra mostra stato effimero. Allo stesso modo, non usare il costo stimato come unico indicatore di qualità: una sessione breve può produrre un risultato errato, una lunga può essere giustificata da un test complesso.

Nel percorso Second Brain con Claude Cowork e Code puoi collegare questo livello visivo a procedure e ricevute: la barra ti dice dove sei, i file dicono che cosa devi fare e le prove dicono se il task è davvero concluso.