Gestire le sessioni

Assegnare nomi, riprendere, creare rami e passare tra conversazioni di Claude Code. Copre --continue, --resume, --from-pr, il selezionatore /resume, la denominazione delle sessioni, l'esportazione dei trascritti e dove vengono archiviati i trascritti.

Una sessione è una conversazione salvata legata a una directory di progetto. Claude Code la archivia localmente mentre lavori, così puoi riprendere da dove hai lasciato, creare un branch per provare un approccio diverso, o passare tra attività.

L'app desktop, claude.ai/code e l'estensione VS Code mantengono ciascuno la propria cronologia delle sessioni, e l'app desktop può anche riprendere una sessione CLI. Questa pagina copre la CLI.

Riprendere una sessione

Le sessioni vengono salvate continuamente in file di trascrizione locali mentre lavori, così puoi tornarci dopo essere uscito o aver eseguito /clear. Usa questi punti di accesso:

Riprendere una sessione in background in esecuzione

Quando la conversazione che riprendi con claude --resume o /resume appartiene a una sessione in background ancora in esecuzione, Claude Code apre direttamente la sessione in esecuzione. Con --bg sulla riga di comando, la ripresa diventa invece un invio in background. Prima della v2.1.285, Claude Code rifiutava e ti diceva di aprire la sessione con claude attach <id>, oppure di arrestarla prima con claude stop <id>.

• Dalla tua shell: claude --resume <session> esegue claude attach su quella sessione nello stesso terminale invece di caricare autonomamente la trascrizione. Un prompt che passi sulla riga di comando, come in claude --resume <session> "check the tests too", viene prima inviato alla sessione come suo turno successivo, e Claude Code stampa Sent your prompt to the background session (<id>); opening it… prima di collegarsi. claude -p --resume <session> "prompt" digitato in un terminale fa lo stesso, quindi -p non rende quell'esecuzione non interattiva.

  Claude Code non apre la sessione quando la riga di comando contiene uno qualsiasi di questi elementi:

  • Input o output tramite pipe o reindirizzati
  • Flag che configurano la sessione, come --permission-mode, --model o --settings
  • Flag che leggono l'output, come --output-format json o --json-schema
  • Flag che limitano o riavvolgono l'esecuzione, come --max-turns o --max-budget-usd

  Con uno qualsiasi di questi, oppure quando la vista agenti è disattivata, Claude Code non invia nulla ed esce con stato 1, indicando che la sessione è in esecuzione in background insieme al comando claude attach <id> che la apre, oppure dicendoti di cercarla in claude agents quando non riesce a determinare l'ID. Aggiungi --fork-session per riprendere invece una copia della conversazione. Per continuare la conversazione stessa in una sessione tua, con i tuoi flag applicati, esegui claude stop <id> e poi ripeti il comando.

  Un prompt che inizia con / o ! non viene inviato, e nemmeno qualsiasi prompt mentre la sessione attende la tua risposta a una domanda. In entrambi i casi Claude Code non apre la sessione, e il messaggio include Your prompt was not sent to it con il motivo.

• Dall'interno di una sessione: /resume sposta la tua conversazione corrente in background e collega questo terminale alla sessione in esecuzione, stampando Opening "<title>", running in the background (<id>). Premi ← su un prompt vuoto per tornare alla vista agenti, che elenca anche la conversazione che hai lasciato. Quando la conversazione corrente non può essere spostata in background, ad esempio perché sei già collegato a una sessione in background o la persistenza delle sessioni è disattivata, /resume stampa invece il comando claude attach da eseguire.

Cosa ripristina una sessione ripresa

Quando Claude Code carica una conversazione dalla sua trascrizione, la sessione ripresa ripristina la conversazione insieme allo stato salvato in essa:

• Cronologia della conversazione: i messaggi, le chiamate agli strumenti e i risultati. Se la sessione è stata compattata, la conversazione si apre su una riga Conversation compacted. Claude continua con il riepilogo dell'ultima compattazione, i messaggi che quella compattazione ha lasciato non riepilogati e ogni messaggio successivo. I messaggi riepilogati dall'ultima compattazione non vengono caricati di nuovo.
• Chiamate agli strumenti interrotte: uno strumento ancora in esecuzione quando il processo precedente è terminato, ad esempio in seguito a un crash, non viene rieseguito quando riprendi.
• Modello: la sessione continua con il modello che stava usando, tranne nei casi descritti in Impostare il modello.
• Agente: una sessione avviata con --agent o con l'impostazione agent continua come quell'agente, mantenendo le sue restrizioni sugli strumenti e il suo modello. Passa --agent quando riprendi per sceglierne un altro; per il prompt di sistema in entrambi i casi, consulta Flag del prompt di sistema nelle conversazioni riprese. Claude Code cerca l'agente in due posizioni: la directory originale della sessione, a condizione che tu abbia considerato attendibile quel workspace, e poi la directory da cui riprendi, così un agente con ambito di progetto viene comunque caricato quando riprendi da un'altra directory. Se Claude Code non trova l'agente in nessuna delle due posizioni, la sessione riprende con gli strumenti predefiniti e mostra un avviso che indica il nome dell'agente.
• Modalità di permesso: se riprendi da un terminale con claude --continue, claude --resume <session-id> o claude --resume <name> quando il nome corrisponde a una sola sessione, senza -p, Claude Code ripristina la modalità di permesso in cui si trovava la sessione, tranne nei casi descritti in modalità di permesso alla ripresa, che tratta anche il selettore delle sessioni, /resume e la ripresa con claude -p. Passa --permission-mode o --dangerously-skip-permissions per sovrascrivere la modalità ripristinata.
• Obiettivo attivo: un obiettivo ancora attivo al termine della sessione viene mantenuto; il suo conteggio dei turni, il timer e la base di riferimento della spesa in token vengono azzerati.
• Attività pianificate con ambito di sessione: le attività non scadute vengono ripristinate. Le attività Bash in background e di monitoraggio no.
• Lavoro in background: un subagent in background, un comando Bash in background o un workflow terminato insieme al processo precedente compare nella trascrizione ripresa come una nota che indica che non è stato completato. Claude Code non avvia un turno a partire da queste note; Claude le legge insieme al tuo prompt successivo.

Non tutti i flag di configurazione dell'avvio originale vengono ripristinati. Se la sessione dipendeva da --mcp-config, --settings, --plugin-dir, --fallback-model o da directory aggiunte con --add-dir, passali di nuovo quando riprendi; nemmeno le directory aggiunte durante la sessione con /add-dir vengono ripristinate, anche se il selettore delle sessioni le usa comunque per individuare la sessione. I file di impostazioni standard, come settings.json e settings.local.json, vengono riletti all'avvio, quindi la configurazione che si trova in essi non deve essere passata di nuovo. Per --system-prompt e --append-system-prompt, consulta Flag del prompt di sistema nelle conversazioni riprese.

Modalità di permesso alla ripresa

La modalità di permesso in cui Claude Code avvia una sessione ripresa dipende da come la riprendi. I casi seguenti si applicano quando Claude Code carica la conversazione dalla sua trascrizione; quando invece apri una sessione in background ancora in esecuzione, quella sessione mantiene la modalità di permesso in cui si trova.

• Terminale: claude --continue, claude --resume <session-id> o claude --resume <name> quando il nome corrisponde a una sola sessione, senza -p. Claude Code ripristina la modalità di permesso in cui si trovava la sessione, tranne nei casi indicati nella tabella. Passa --permission-mode o --dangerously-skip-permissions per sovrascrivere la modalità ripristinata.
• Non interattivo: claude -p --resume o claude -p --continue. Claude Code avvia l'esecuzione nella modalità di permesso in cui partirebbe una nuova esecuzione di claude -p, tranne per il fatto che una sessione terminata in plan mode riprende in plan mode alle condizioni indicate di seguito.
• VS Code: il pannello della conversazione dell'estensione. La tabella copre solo una conversazione terminata in plan mode; per il resto, consulta riprendere conversazioni passate.
• Selettore delle sessioni all'avvio: una sessione che selezioni dal selettore delle sessioni, sia che tu l'abbia aperto con claude --resume da solo, con claude --from-pr o con un nome che corrisponde a più di una sessione. Claude Code avvia la sessione nella modalità di permesso in cui avvierebbe una nuova sessione dalla stessa riga di comando, tranne per il fatto che una sessione terminata in plan mode riprende in plan mode. Se passi --permission-mode, --dangerously-skip-permissions o --fork-session, Claude Code non ripristina il plan mode. Nessun'altra modalità di permesso memorizzata viene ripristinata.
• /resume all'interno di una sessione, con o senza argomento: la conversazione a cui passi continua nella modalità di permesso in cui si trova la tua sessione corrente, tranne per il fatto che una conversazione terminata in plan mode riprende in plan mode, anche se hai avviato Claude Code con --permission-mode o --dangerously-skip-permissions. Se quella conversazione era già stata aperta in precedenza durante questa esecuzione di Claude Code, come la conversazione con cui hai iniziato o una che hai lasciato con /clear o /resume, continua invece nella tua modalità di permesso corrente.

Se una regola di negazione rimuove lo strumento ExitPlanMode, Claude non può presentare un piano per l'approvazione, quindi Claude Code non ripristina il plan mode. La sessione si avvia nella modalità di permesso in cui si avvierebbe una nuova sessione dalla stessa riga di comando. Con /resume, la conversazione continua nella tua modalità di permesso corrente.

Il ripristino del plan mode nei percorsi non interattivo e VS Code richiede Claude Code v2.1.246 o versioni successive. Ogni riga indica la modalità di permesso in cui è terminata la sessione, quale dei percorsi tra terminale, non interattivo e VS Code usi per riprenderla, e la modalità di permesso in cui Claude Code avvia la sessione ripresa.

Riprendere in plan mode con -p

Un'esecuzione di claude -p --resume o claude -p --continue riprende in plan mode solo quando valgono tutte queste condizioni:

• Passi --permission-prompt-tool e non passi --permission-prompts none, in modo che Claude Code possa presentare il piano per l'approvazione
• Non passi --permission-mode né --dangerously-skip-permissions
• Non passi --fork-session
• L'esecuzione non viene avviata tramite canali
• Nessuna regola di negazione rimuove lo strumento ExitPlanMode

La finestra di dialogo "Resume this conversation?"

Se vedi la finestra di dialogo "Resume this conversation?" quando riprendi una sessione, la sua stima è la quota del tuo limite di utilizzo di 5 ore che userebbe la sola conversazione salvata. La stima non conta ciò che hai già usato.

Nei piani Pro, Max e Ultra, la finestra di dialogo può comparire quando riprendi una conversazione lunga dopo una lunga pausa o con un modello diverso. L'utilizzo stimato viene conteggiato quando invii il primo messaggio dopo Resume, non quando lo selezioni. Scegli in base al fatto che la tua prossima attività abbia ancora bisogno della conversazione salvata:

• Resume: continua a lavorare nella conversazione salvata.
• Start a new conversation: passa a un lavoro che non ha bisogno della conversazione salvata. Per riaprirla in seguito, esegui /resume al prompt. La stima non si applica al tuo primo messaggio nella nuova conversazione. Se l'opzione indica che Claude può consultare questa conversazione, puoi comunque fare riferimento al lavoro precedente nella nuova conversazione.

Dove cerca il selettore delle sessioni

Claude Code memorizza le sessioni per directory di progetto. Per impostazione predefinita il selettore delle sessioni mostra:

• Le sessioni del worktree corrente, incluse le sessioni in background, contrassegnate con bg nell'elenco
• Le sessioni avviate altrove che hanno aggiunto la directory corrente con /add-dir

Usa Ctrl+W per estendere la ricerca a tutti i worktree del repository o Ctrl+A per estenderla a tutti i progetti su questa macchina.

/loop, -p, Agent SDK e sessioni in background

Le sessioni il cui primo prompt era un comando /loop non compaiono nel selettore, e anche claude --continue le salta. Eseguire /loop più avanti in una conversazione non nasconde la sessione.

Claude Code esclude le sessioni create con claude -p o con l'Agent SDK dal selettore delle sessioni e da claude --continue. Puoi comunque riprenderne una passando il suo ID di sessione a claude --resume <session-id>. Quando esegui claude -p --continue, Claude Code include le sessioni -p, SDK e /loop.

claude --continue apre una sessione in background che è terminata, ma non una ancora in esecuzione; l'apertura delle sessioni in background terminate richiede Claude Code v2.1.257 o versioni successive. Se la tua conversazione più recente è una che hai spostato in background ed è ancora in esecuzione lì, Claude Code esce con Your most recent conversation is running in the background e l'ID di quella sessione. Collegati alla sessione da claude agents, oppure esegui claude --resume per sceglierne un'altra.

Sessioni in altri worktree e progetti

Quando selezioni una sessione da un altro worktree dello stesso repository, Claude Code la riprende sul posto; quando il worktree della sessione non esiste più, Claude Code la riprende nella tua directory corrente. Quando selezioni una sessione da un progetto non correlato, Claude Code copia invece negli appunti un comando cd e di ripresa. Se la directory di quel progetto non esiste più, Claude Code riprende la sessione nella tua directory corrente invece di copiare un comando cd che fallirebbe.

Spostare una sessione con /cd la trasferisce nell'archivio di progetto della nuova directory, quindi in seguito compare nel selettore di quella directory.

Riprendere per ID di sessione o per nome

Puoi eseguire claude --resume <session-id> da qualsiasi directory, quindi puoi riprendere una sessione avviata altrove o spostata con /cd. Claude Code cerca l'ID in questo ordine:

1. La directory del progetto corrente e i suoi worktree Git
2. Tutti gli altri progetti su questa macchina

La ricerca tra progetti risolve l'ID solo quando esattamente un altro progetto contiene una trascrizione con messaggi per quell'ID, quindi un duplicato copiato a mano fa sì che Claude Code segnali che non è stato trovato invece di riprendere una copia arbitraria. Se nessuna sessione memorizzata corrisponde all'ID, Claude Code segnala No conversation found with session ID: <session-id>.

La ripresa per nome viene risolta nel repository corrente e nei suoi worktree. Entrambe le forme cercano una corrispondenza esatta e la riprendono direttamente anche se si trova in un worktree diverso:

Assegna un nome alle tue sessioni

Assegna alle sessioni nomi descrittivi in modo che siano facili da trovare nel selettore delle sessioni e riprendibili per nome. Questo è particolarmente importante quando lavori su più attività in parallelo.

Dopo aver assegnato un nome a una sessione tramite la CLI o da claude.ai, puoi tornarci con claude --resume <name> o /resume <name>; una sessione dell'app desktop si riprende nell'app desktop. Consulta Riprendere una sessione per scoprire come funziona la risoluzione dei nomi tra i worktree.

Le sessioni a cui non assegni un nome ricevono comunque due etichette assegnate da Claude Code. Solo il titolo generato funziona come identificativo per la ripresa:

• Nome visualizzato predefinito: le sessioni interattive a cui non assegni mai un nome ricevono comunque un nome visualizzato predefinito all'avvio. Il nome predefinito combina il nome della directory di lavoro con un suffisso di due caratteri, ad esempio my-app-3f, e identifica la sessione negli elenchi delle sessioni in esecuzione, come la vista agenti e l'output di claude agents --json. Il nome predefinito non è un identificativo per la ripresa. Se lo passi a claude --resume o /resume, Claude Code non trova la sessione.

• Titolo generato: se non assegni un nome a una sessione, Claude Code genera un titolo per la sessione. Il titolo è un breve riepilogo del tuo primo prompt, scritto da una richiesta in background al modello piccolo/veloce, normalmente un modello di classe Haiku. Un'esecuzione di claude -p avviata direttamente da una shell o da uno script non ne riceve uno.

  Accettare un piano sostituisce il titolo generato con un titolo basato sul piano. Puoi passare entrambi i titoli a claude --resume o /resume, e Claude Code li risolve allo stesso modo di un nome che hai impostato tu.

Usare il selezionatore di sessioni

Esegui /resume all'interno di una sessione, o claude --resume senza argomenti, per aprire il selezionatore di sessioni interattivo. Usa queste scorciatoie da tastiera per navigare, cercare e ampliare l'elenco:

Ogni riga mostra il nome della sessione se impostato, altrimenti il titolo della sessione generato dall'IA, il riassunto della conversazione o il primo prompt, insieme al tempo dall'ultima attività, al branch git e alla dimensione del file.

Le sessioni create con /branch o --fork-session ottengono i propri ID di sessione e appaiono come righe separate. Quando il selezionatore trova più di una voce per la stessa sessione, le raggruppa sotto una singola riga. Premi → per espandere un gruppo.

Se Claude Code non riesce a caricare la sessione che selezioni dal selezionatore claude --resume, stampa Failed to resume the conversation con un comando per riprovare, quindi esce con codice 1. Dal selezionatore /resume all'interno di una sessione, Claude Code segnala l'errore e la tua conversazione corrente continua a funzionare.

Creare un ramo di una sessione

La creazione di un ramo crea una copia della conversazione finora e ti passa in essa, lasciando l'originale intatto. Usalo per provare un approccio diverso senza perdere il percorso su cui eri.

Da dentro una sessione, esegui /branch con un nome opzionale:

/branch try-streaming-approach

Se ometti il nome, Claude Code assegna un nome al nuovo branch in base al primo prompt nella conversazione.

Dalla riga di comando, combina --continue o --resume con --fork-session:

claude --continue --fork-session

La conferma di /branch stampa due ID di sessione: il nuovo ramo in cui sei ora e l'originale. L'originale rimane invariato su disco e rimane nel selezionatore di sessioni; torna ad esso con /resume <original-name> o passando il suo ID a /resume.

/branch copia il trascritto e passa il processo Claude Code in esecuzione a scrivere su di esso. Quella distinzione determina ciò che il ramo eredita:

Se riprendi la stessa sessione in due terminali senza creare un fork, i messaggi di entrambi si intercalano in un unico trascritto. Per il rewind basato su checkpoint all'interno di una singola sessione, vedi Checkpointing.

Gestire il contesto all'interno di una sessione

Questi comandi controllano cosa c'è nella finestra di contesto senza lasciare la sessione:

• /clear: ricomincia da capo con un contesto vuoto. Claude Code salva la sessione precedente; riprendila con /resume, oppure, nello stesso processo Claude Code, dalla voce della sessione precedente del menu rewind. Senza argomenti, la nuova sessione mantiene un nome che hai impostato con --name o /rename, ma non un titolo di sessione generato dall'IA. Per nominare invece la sessione che stai lasciando, passa il nome, come in /clear release-prep; la nuova sessione inizia quindi senza nome
• /compact [instructions]: sostituisci la cronologia con un riassunto, facoltativamente focalizzato su ciò che specifichi
• /context: mostra cosa sta attualmente consumando contesto

Per come la compattazione interagisce con CLAUDE.md, skill e regole, vedi la guida della finestra di contesto. Per strategie su quando cancellare rispetto a compattare, vedi Best practice.

Esportare e individuare i dati della sessione

Esegui /export per aprire un menu che ti consente di copiare la conversazione corrente negli appunti o salvarla come file di testo semplice, con messaggi e output degli strumenti renderizzati come testo leggibile. Passa un nome file per saltare il menu e scrivere direttamente in quel file.

Accedere alle conversazioni da script

/export produce una trascrizione renderizzata per una persona da leggere. Le interfacce di seguito producono dati strutturati per uno script da analizzare: un risultato JSON da un'esecuzione, il percorso al file di trascrizione di una sessione, o un flusso live di eventi. Scegli in base a ciò che attiva lo script:

• Esegui Claude una volta e cattura il risultato: invoca claude -p con --output-format json o stream-json per catturare il risultato, l'ID della sessione, l'utilizzo e il costo di un'esecuzione non interattiva come JSON strutturato.
• Poni una domanda a una sessione esistente: passa un ID di sessione a claude -p --resume per inviare un prompt di follow-up, come una richiesta di riepilogo, e catturare la risposta strutturata.
• Reagisci agli eventi della sessione: leggi il campo transcript_path che hooks e comandi della riga di stato ricevono come input. Un hook SessionEnd può archiviare la trascrizione quando una sessione termina.
• Incorpora Claude in un'app TypeScript o Python: usa l'Agent SDK per ricevere ogni messaggio a livello di programmazione.

L'esempio di seguito utilizza la seconda interfaccia. Invia un prompt di follow-up a una sessione esistente e legge la risposta con jq:

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

Dove vengono archiviati i trascritti

Per impostazione predefinita, Claude Code archivia i trascritti come JSONL in ~/.claude/projects/<project>/<session-id>.jsonl, dove <project> è il percorso della directory di lavoro con caratteri non alfanumerici sostituiti da -. Per una directory di lavoro il cui nome convertito supera i 200 caratteri, Claude Code tronca il nome a 200 caratteri e aggiunge un hash del percorso completo, in modo che il nome della directory rimanga entro i limiti del file system.

Ogni riga è un oggetto JSON: un messaggio, un uso o un risultato di uno strumento, un record di una richiesta che Claude Code ha inviato al modello, o una voce di metadati. Il formato della voce è interno a Claude Code e cambia tra le versioni, quindi gli script che analizzano direttamente questi file possono interrompersi in qualsiasi rilascio. Per costruire sui dati della sessione, utilizza /export o le interfacce di script invece.

La posizione, la conservazione e il comportamento di scrittura sono configurabili:

Eliminare i dati della sessione

Le trascrizioni scadono secondo le regole di pulizia della conservazione. Per eliminare le trascrizioni di un progetto e lo stato correlato più rapidamente, esegui claude purge. Se elimini una sessione in background con claude rm <id>, la sua trascrizione rimane su disco e resta disponibile tramite claude --resume.

Assegna un nome alla directory del progetto tu stesso

Per impostazione predefinita, Claude Code deriva il nome <project> dall'intero percorso della directory di lavoro. Per scegliere il nome tu stesso, imposta CLAUDE_CODE_PROJECT_DIR_NAME insieme a CLAUDE_CONFIG_DIR. Claude Code quindi archivia i trascritti di quella sessione e la memoria automatica sotto il tuo nome. Questo è adatto a un host che incorpora Claude Code e assegna a ogni sessione la propria directory di configurazione. Richiede Claude Code v2.1.234 o successivo.

Ad esempio, questo avvio mantiene i dati del tenant A in /srv/tenant-a e assegna un nome alla sua directory del progetto work:

CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude

Claude Code scrive i trascritti della sessione in /srv/tenant-a/projects/work/ e la sua memoria automatica in /srv/tenant-a/projects/work/memory/, indipendentemente dalla directory di lavoro.

Tre regole si applicano quando lo imposti:

• Imposta anche CLAUDE_CONFIG_DIR: il nome non varia con la directory di lavoro, quindi sotto il valore predefinito ~/.claude unirebbe i trascritti e la memoria automatica di ogni progetto in una directory. Claude Code ignora CLAUDE_CODE_PROJECT_DIR_NAME quando CLAUDE_CONFIG_DIR non è impostato.
• Usa 1-64 lettere, cifre, trattini o sottolineature: non utilizzare un nome di dispositivo Windows come con. Claude Code ignora qualsiasi altro valore e utilizza il nome derivato.
• Impostalo nell'ambiente shell che avvia claude: Claude Code lo legge una sola volta all'avvio da quell'ambiente, quindi un blocco env in un file di impostazioni non può impostarlo.

Una volta che hai assegnato un nome alla directory del progetto di una directory di configurazione, continua ad avviare con quel nome. Se avvii Claude Code con lo stesso CLAUDE_CONFIG_DIR ma senza CLAUDE_CODE_PROJECT_DIR_NAME, legge e scrive di nuovo la directory derivata. Le sessioni archiviate con il tuo nome rimangono su disco: premi Ctrl+A nel selettore di sessione per elencare le sessioni da ogni directory del progetto in quella directory di configurazione, inclusa quella fissata, e in qualunque modo tu avvii, claude --resume <session-id> trova una sessione archiviata con uno dei due nomi.

Vedi anche

Queste pagine coprono la meccanica correlata delle sessioni e del parallelismo:

• Worktrees: esegui sessioni parallele isolate su rami separati
• Checkpointing: riavvolgi il codice e la conversazione a un punto precedente
• Context window: cosa riempie il contesto e cosa sopravvive alla compattazione
• Non-interactive mode: comportamento della sessione in claude -p