Gérer les sessions

Nommez, reprenez, créez des branches et basculez entre les conversations Claude Code. Couvre --continue, --resume, --from-pr, le sélecteur /resume, la dénomination des sessions, l'export des transcriptions et l'emplacement des transcriptions.

Une session est une conversation enregistrée liée à un répertoire de projet. Claude Code la stocke localement au fur et à mesure que vous travaillez, ce qui vous permet de reprendre là où vous vous êtes arrêté, de créer une branche pour essayer une approche différente ou de basculer entre les tâches.

L'application de bureau, Claude Code sur le web et l'extension VS Code maintiennent chacun leur propre historique de sessions. Cette page couvre l'interface CLI.

Reprendre une session

Les sessions sont enregistrées en continu dans les fichiers de transcription locaux au fur et à mesure que vous travaillez, ce qui vous permet de revenir à l'une d'elles après avoir quitté ou exécuté /clear. Utilisez ces points d'entrée :

Claude Code laisse les sessions créées avec claude -p ou le SDK Agent en dehors du sélecteur de sessions et en dehors de claude --continue. Vous pouvez toujours en reprendre une en passant son ID de session à claude --resume <session-id>. Avec claude --continue, Claude Code ignore également les sessions dont la première invite était /loop. Lorsque vous exécutez claude -p --continue, Claude Code inclut les sessions -p, SDK et /loop.

claude --continue ouvre une session en arrière-plan qui s'est terminée, mais pas une qui est toujours en cours d'exécution ; l'ouverture de sessions en arrière-plan terminées nécessite Claude Code v2.1.257 ou ultérieur. Si votre conversation la plus récente est une que vous avez envoyée en arrière-plan et qu'elle s'exécute toujours là-bas, Claude Code se termine avec Your most recent conversation is running in the background et l'ID de cette session. Attachez-vous à la session depuis claude agents, ou exécutez claude --resume pour en choisir une autre.

Vous pouvez exécuter claude --resume <session-id> depuis n'importe quel répertoire : Claude Code cherche l'ID dans le répertoire de projet courant et ses git worktrees d'abord, puis dans tous les autres projets sur cette machine, ce qui lui permet de trouver une session qui a démarré ailleurs ou qui s'est déplacée avec /cd. La recherche inter-projets résout l'ID uniquement lorsqu'exactement un autre projet contient une transcription avec des messages pour celui-ci, donc un doublon copié à la main fait que Claude Code signale non-trouvé plutôt que de reprendre une copie arbitraire. Si aucune session stockée ne correspond à l'ID, Claude Code signale No conversation found with session ID: <session-id>. Avant la v2.1.223, la recherche s'arrêtait au répertoire de projet courant et à ses git worktrees, donc vous deviez reprendre depuis le répertoire dans lequel la session avait travaillé en dernier.

Ce qu'une session reprise restaure

Une session reprise restaure la conversation ainsi que l'état enregistré en elle :

• Historique de conversation : l'historique complet, y compris les appels d'outils et les résultats. Un outil qui était toujours en cours d'exécution lorsque le processus précédent s'est terminé, par exemple lors d'un plantage, ne se termine pas ou ne s'exécute pas à nouveau lorsque vous reprenez ; Claude continue sans sa sortie.
• Modèle : la session continue sur le modèle qu'elle utilisait. Le modèle n'est pas restauré lorsqu'il a été retiré ou n'est pas autorisé par availableModels, lorsqu'un drapeau --model ou une variable d'environnement de la famille ANTHROPIC_MODEL en choisit un au lancement, ou sur les fournisseurs qui utilisent des ID de déploiement spécifiques au fournisseur, tels que Amazon Bedrock, Google Cloud's Agent Platform et Microsoft Foundry ; voir configuration du modèle pour l'ordre de résolution.
• Agent : une session démarrée avec --agent ou le paramètre agent continue en tant que cet agent, en conservant ses restrictions d'outils et son modèle. Passez --agent lors de la reprise pour en choisir un différent ; pour l'invite système dans l'un ou l'autre cas, voir Drapeaux d'invite système dans les conversations reprises. Claude Code cherche l'agent dans deux endroits : le répertoire d'origine de la session, à condition que vous ayez approuvé cet espace de travail, puis le répertoire depuis lequel vous reprenez, donc un agent limité au projet se charge toujours lorsque vous reprenez depuis un autre répertoire. Si Claude Code ne trouve pas l'agent dans l'un ou l'autre endroit, la session reprend avec les outils par défaut et affiche un avertissement nommant l'agent.
• Mode de permission : si vous reprenez depuis un terminal avec claude --continue, claude --resume <session-id> ou claude --resume <name> lorsque le nom correspond à une session, sans -p, Claude Code restaure le mode de permission dans lequel se trouvait la session, sauf dans les cas de mode de permission à la reprise, qui couvre également le sélecteur de sessions, /resume et la reprise avec claude -p. Passez --permission-mode ou --dangerously-skip-permissions pour remplacer le mode restauré.
• Objectif actif : un objectif qui était toujours actif lorsque la session s'est terminée se poursuit ; son nombre de tours, son minuteur et sa ligne de base de dépense de jetons se réinitialisent.
• Tâches planifiées : les tâches qui n'ont pas expiré sont restaurées. Les tâches Bash en arrière-plan et les tâches de surveillance ne le sont pas.

Tous les drapeaux de configuration du lancement d'origine ne sont pas restaurés. Si la session dépendait de --mcp-config, --settings, --plugin-dir, --fallback-model ou de répertoires ajoutés avec --add-dir, passez-les à nouveau lorsque vous reprenez ; les répertoires ajoutés en milieu de session avec /add-dir ne sont pas restaurés non plus, bien que le sélecteur de sessions les utilise toujours pour localiser la session. Les fichiers de paramètres standard, tels que settings.json et settings.local.json, sont relus au lancement, donc la configuration qui s'y trouve n'a pas besoin d'être passée à nouveau. Pour --system-prompt et --append-system-prompt, voir Drapeaux d'invite système dans les conversations reprises.

Mode de permission à la reprise

Le mode de permission dans lequel Claude Code démarre une session reprise dépend de la façon dont vous la reprenez :

• Terminal : claude --continue, claude --resume <session-id> ou claude --resume <name> lorsque le nom correspond à une session, sans -p. Claude Code restaure le mode de permission dans lequel se trouvait la session, sauf dans les cas du tableau. Passez --permission-mode ou --dangerously-skip-permissions pour remplacer le mode restauré.
• Non-interactif : claude -p --resume ou claude -p --continue. Claude Code démarre l'exécution dans le mode de permission qu'une nouvelle exécution claude -p démarrerait, sauf qu'une session qui s'est terminée en mode plan reprend en mode plan selon les conditions ci-dessous.
• VS Code : le panneau de conversation de l'extension. Le tableau couvre uniquement une conversation qui s'est terminée en mode plan ; pour le reste, voir reprendre les conversations passées.
• Sélecteur de sessions au lancement : une session que vous sélectionnez dans le sélecteur de sessions, que vous l'ayez ouvert avec claude --resume seul, claude --from-pr ou un nom qui correspond à plus d'une session. Claude Code ne restaure pas le mode de permission stocké. Il démarre la session dans le mode de permission qu'il démarrerait une nouvelle session depuis la même ligne de commande.
• /resume à l'intérieur d'une session, avec ou sans argument : Claude Code ne restaure pas le mode de permission stocké. La conversation vers laquelle vous basculez continue dans le mode de permission dans lequel se trouve votre session actuelle.

La restauration du mode plan sur les chemins non-interactif et VS Code nécessite Claude Code v2.1.246 ou ultérieur. Chaque ligne nomme le mode de permission dans lequel la session s'est terminée, lequel des chemins terminal, non-interactif et VS Code vous la reprenez par, et le mode de permission dans lequel Claude Code démarre la session reprise.

Reprendre en mode plan avec `-p`

Une exécution claude -p --resume ou claude -p --continue reprend en mode plan uniquement lorsque les quatre conditions sont remplies :

• Vous passez --permission-prompt-tool, afin que Claude Code puisse présenter le plan pour approbation
• Vous ne passez pas --permission-mode ou --dangerously-skip-permissions
• Vous ne passez pas --fork-session
• L'exécution n'est pas démarrée via les canaux

Reprendre à partir d'un résumé

Sur un plan Pro ou Max, lorsque vous reprenez une session qui a été inactive pendant plus d'une heure environ et dépasse 100 000 jetons, Claude Code restaure la conversation puis ouvre une boîte de dialogue avant que vous n'envoyiez votre premier message. Le cache de prompt de la session a expiré à ce moment-là, donc la prochaine demande traite l'historique complet une fois, quel que soit l'option de la boîte de dialogue que vous choisissez.

La boîte de dialogue offre trois façons de continuer la session. Elles diffèrent dans la quantité de conversation que chacune porte dans les demandes ultérieures, ce qui est un compromis entre conserver tous les détails et envoyer moins de jetons par demande :

• Reprendre à partir du résumé : exécute /compact immédiatement. Claude Code envoie une demande de résumé sur l'historique complet, puis remplace l'historique par le résumé, vos échanges les plus récents et jusqu'à cinq fichiers récemment lus. Les demandes ultérieures portent le résumé au lieu de l'historique complet.
• Reprendre la session complète telle quelle : charge la conversation inchangée. Après que vous ayez envoyé votre premier message, Claude Code retraite et re-met en cache l'historique complet, puis le relit à partir du cache sur les demandes ultérieures tant que le cache reste actif.
• Ne me le demandez plus : reprend la session complète et arrête d'afficher la boîte de dialogue sur toutes les reprises futures.

Reprendre tel quel conserve tous les détails de la conversation disponibles, à un coût par demande qui s'adapte à la taille de la conversation. Reprendre à partir du résumé coûte moins cher à chaque demande ultérieure car il porte le résumé au lieu de l'historique complet, mais tout ce que le résumé omet n'est plus dans le contexte de Claude. Voir pourquoi l'utilisation augmente dans une longue session pour savoir d'où provient ce coût par demande.

Où le sélecteur de sessions cherche

Claude Code stocke les sessions par répertoire de projet. Par défaut, le sélecteur de sessions affiche :

• Les sessions du worktree courant, y compris les sessions en arrière-plan, qui sont marquées bg dans la liste
• Les sessions démarrées ailleurs qui ont ajouté le répertoire courant avec /add-dir

Utilisez Ctrl+W pour élargir à tous les worktrees du référentiel ou Ctrl+A pour élargir à chaque projet sur cette machine.

Les sessions dont la première invite était une commande /loop n'apparaissent pas dans le sélecteur, et claude --continue les ignore également. L'exécution de /loop plus tard dans une conversation ne masque pas la session. Avant la v2.1.211, une exécution /loop au début d'une conversation masquait la session du sélecteur de manière permanente.

Le déplacement d'une session avec /cd la réinstalle dans le stockage de projet du nouveau répertoire, ce qui la fait apparaître dans le sélecteur de ce répertoire par la suite. À partir de la v2.1.196, une session déplacée reste absente du sélecteur de l'ancien répertoire même après un plantage ou une fermeture forcée. Sur les versions antérieures, elle pouvait aussi réapparaître dans la liste de l'ancien répertoire après une fermeture qui n'était pas propre lorsque l'ancien chemin contenait des caractères spéciaux tels que des traits de soulignement.

Lorsque vous sélectionnez une session d'un autre worktree du même référentiel, Claude Code la reprend sur place ; lorsque le propre worktree de la session n'existe plus, Claude Code la reprend dans votre répertoire courant. Lorsque vous sélectionnez une session d'un projet non lié, Claude Code copie une commande cd et de reprise dans votre presse-papiers à la place. Si le répertoire de ce projet n'existe plus, Claude Code reprend la session dans votre répertoire courant plutôt que de copier une commande cd qui échouerait.

La reprise par nom se résout dans le référentiel courant et ses worktrees. Les deux formes recherchent une correspondance exacte et la reprennent directement même si elle se trouve dans un worktree différent :

Nommer vos sessions

Donnez aux sessions des noms descriptifs pour qu'elles soient trouvables dans le sélecteur de sessions et reprises par nom. Cela est particulièrement important lorsque vous travaillez sur plusieurs tâches en parallèle.

Une fois qu'une session est nommée via une route CLI ou depuis claude.ai, revenez-y avec claude --resume <name> ou /resume <name> ; une session d'application de bureau reprend dans l'application, qui conserve son propre historique de sessions. Voir Reprendre une session pour savoir comment la résolution des noms se comporte entre les worktrees.

Lorsque vous démarrez ou reprenez une session interactive avec un nom qu'une autre session active sur cette machine utilise déjà, ou que vous renommez une session avec un tel nom, Claude Code laisse le nom à la session qui l'a déjà, renomme la vôtre en une variante avec un suffixe de deux mots, comme auth-refactor-graceful-unicorn, et vous le signale. Exécutez /rename avec un nouveau nom si vous préférez en choisir un vous-même. Avant la v2.1.232, les deux sessions conservaient le nom.

Dans trois cas, Claude Code ne renomme pas le doublon, vous pouvez donc toujours voir deux sessions avec le même nom dans les listes :

• Il ne vérifie pas les titres générés par l'IA ou les noms d'affichage par défaut.
• Il ne vérifie pas le --name d'une session arrière-plan ou -p au démarrage.
• Il ne peut pas renommer une session sur une version antérieure de Claude Code.

Les sessions que vous ne nommez pas reçoivent quand même deux étiquettes que Claude Code attribue. Seul le titre généré fonctionne comme handle de reprise :

• Nom d'affichage par défaut : les sessions interactives que vous ne nommez jamais reçoivent quand même un nom d'affichage par défaut au démarrage. Nécessite Claude Code v2.1.196 ou version ultérieure. Le nom par défaut combine le nom du répertoire de travail avec un suffixe de deux caractères, par exemple my-app-3f, et identifie la session dans les listes de sessions en cours d'exécution, telles que la vue agent et la sortie claude agents --json. Le nom par défaut n'est pas un handle de reprise. Si vous le transmettez à claude --resume ou /resume, Claude Code ne trouve pas la session. Nommer la session remplace le nom par défaut dans ces listes, tout comme l'acceptation d'un plan.
• Titre généré : si vous ne nommez pas une session, Claude Code génère un titre de session pour elle. Le titre est un court résumé de votre première invite, écrit par une demande en arrière-plan au modèle petit/rapide, normalement un modèle de classe Haiku. L'acceptation d'un plan le remplace par un titre basé sur le plan. Nommer la session remplace le titre généré. Vous voyez le titre de la première invite dans le sélecteur de sessions et dans le champ session_name de la barre d'état lorsqu'aucun nom n'est défini. Le titre du plan s'affiche aux mêmes deux endroits et aussi dans les listes de sessions en cours d'exécution, où il remplace le nom d'affichage par défaut. Vous pouvez transmettre l'un ou l'autre titre à claude --resume ou /resume, et Claude Code le résout de la même manière qu'un nom que vous avez défini.

Utiliser le sélecteur de sessions

Exécutez /resume à l'intérieur d'une session, ou claude --resume sans arguments, pour ouvrir le sélecteur de sessions interactif. Utilisez ces raccourcis clavier pour naviguer, rechercher et élargir la liste :

Chaque ligne affiche le nom de la session s'il est défini, sinon le titre de session généré par l'IA, le résumé de la conversation ou la première invite, ainsi que le temps écoulé depuis la dernière activité, la branche git et la taille du fichier. Élargissez à tous les projets avec Ctrl+A pour voir également le chemin du projet de chaque session.

Les sessions créées avec /branch ou --fork-session obtiennent leurs propres ID de session et apparaissent comme des lignes distinctes. Lorsque le sélecteur trouve plus d'une entrée pour la même session, il les groupe sous une seule ligne. Appuyez sur → pour développer un groupe.

Si Claude Code ne peut pas charger la session que vous sélectionnez dans le sélecteur claude --resume, il affiche Impossible de reprendre la conversation avec une commande pour réessayer, puis se termine avec le code 1. À partir du sélecteur /resume à l'intérieur d'une session, Claude Code signale l'échec et votre conversation actuelle continue de s'exécuter.

Créer une branche d'une session

La création d'une branche crée une copie de la conversation jusqu'à présent et vous y bascule, laissant l'original intact. Utilisez-la pour essayer une approche différente sans perdre le chemin sur lequel vous étiez.

À partir d'une session, exécutez /branch avec un nom optionnel :

/branch try-streaming-approach

Si vous omettez le nom, Claude Code nomme la nouvelle branche d'après la première invite de la conversation. À partir de la v2.1.198, cela s'applique également après compaction ; les versions antérieures revenaient au nom littéral Branched conversation au lieu de regarder au-delà du résumé de compaction jusqu'à la première invite originale.

À partir de la ligne de commande, combinez --continue ou --resume avec --fork-session :

claude --continue --fork-session

La confirmation /branch imprime deux ID de session : la nouvelle branche dans laquelle vous êtes maintenant et l'original. L'original est inchangé sur le disque et reste dans le sélecteur de sessions ; revenez-y avec /resume <original-name> ou en passant son ID à /resume.

/branch copie la transcription et bascule le processus Claude Code en cours d'exécution pour écrire dedans. Cette distinction détermine ce que la branche hérite :

Si vous reprenez la même session dans deux terminaux sans créer de branche, les messages des deux s'entrelacent dans une seule transcription. Pour le rembobinage basé sur les points de contrôle au sein d'une seule session, voir Points de contrôle.

Gérer le contexte au sein d'une session

Ces commandes contrôlent ce qui se trouve dans la fenêtre de contexte sans quitter la session :

• /clear : recommencer avec un contexte vide. Claude Code enregistre la conversation précédente ; reprenez-la avec /resume, ou, dans le même processus Claude Code, depuis l'entrée de session précédente du menu de rembobinage. Sans argument, la nouvelle conversation conserve un nom que vous avez défini avec --name ou /rename, mais pas un titre de session généré par l'IA. Pour nommer la conversation que vous quittez, passez le nom, comme dans /clear release-prep ; la nouvelle conversation démarre alors sans nom
• /compact [instructions] : remplacer l'historique par un résumé, optionnellement axé sur ce que vous spécifiez
• /context : afficher ce qui consomme actuellement le contexte

Pour savoir comment la compaction interagit avec CLAUDE.md, les compétences et les règles, voir le guide de la fenêtre de contexte. Pour les stratégies sur quand effacer par rapport à compacter, voir Meilleures pratiques.

Exporter et localiser les données de session

Exécutez /export pour ouvrir un menu qui vous permet de copier la conversation courante dans votre presse-papiers ou de l'enregistrer en tant que fichier texte brut, avec les messages et les sorties d'outils rendus sous forme de texte lisible. Passez un nom de fichier pour ignorer le menu et écrire directement dans ce fichier.

Accéder aux conversations à partir de scripts

/export produit une transcription rendue pour qu'une personne la lise. Les interfaces ci-dessous produisent des données structurées pour qu'un script les analyse : un résultat JSON d'une exécution, le chemin vers le fichier de transcription d'une session, ou un flux en direct d'événements. Choisissez en fonction de ce qui déclenche le script :

• Exécuter Claude une fois et capturer le résultat : invoquez claude -p avec --output-format json ou stream-json pour capturer le résultat, l'ID de session, l'utilisation et le coût d'une exécution non interactive sous forme de JSON structuré.
• Poser une question à une session existante : passez un ID de session à claude -p --resume pour envoyer une invite de suivi, comme une demande de résumé, et capturer la réponse structurée.
• Réagir aux événements de session : lisez le champ transcript_path que les hooks et les commandes de ligne d'état reçoivent en entrée. Un hook SessionEnd peut archiver la transcription lorsqu'une session se termine.
• Intégrer Claude dans une application TypeScript ou Python : utilisez le Agent SDK pour recevoir chaque message par programmation.

L'exemple ci-dessous utilise la deuxième interface. Il envoie une invite de suivi à une session existante et lit la réponse avec jq :

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

Où les transcriptions sont stockées

Par défaut, Claude Code stocke les transcriptions en JSONL à ~/.claude/projects/<project>/<session-id>.jsonl, où <project> est votre chemin de répertoire de travail avec les caractères non alphanumériques remplacés par -. Pour un répertoire de travail dont le nom converti dépasse 200 caractères, Claude Code tronque le nom à 200 caractères et ajoute un hash du chemin complet, de sorte que le nom du répertoire reste dans les limites du système de fichiers.

Chaque ligne est un objet JSON pour un message, une utilisation d'outil ou une entrée de métadonnées. Le format d'entrée est interne à Claude Code et change entre les versions, donc les scripts qui analysent directement ces fichiers peuvent se casser à chaque version. Pour construire sur les données de session, utilisez /export ou les interfaces de script à la place.

L'emplacement, la rétention et le comportement d'écriture sont configurables :

Supprimer les données de session

Les transcriptions arrivent à expiration selon les règles de nettoyage de rétention. Pour supprimer les transcriptions d'un projet et l'état associé plus tôt, exécutez claude project purge. Si vous supprimez une session en arrière-plan avec claude rm <id>, sa transcription reste sur le disque et reste disponible via claude --resume.

Nommer le répertoire du projet vous-même

Par défaut, Claude Code dérive le nom <project> du chemin complet du répertoire de travail. Pour choisir le nom vous-même, définissez CLAUDE_CODE_PROJECT_DIR_NAME aux côtés de CLAUDE_CONFIG_DIR. Claude Code stocke ensuite les transcriptions de cette session et la mémoire automatique sous votre nom. Cela convient à un hôte qui intègre Claude Code et donne à chaque session son propre répertoire de configuration. Nécessite Claude Code v2.1.234 ou ultérieur.

Par exemple, ce lancement garde les données du locataire A sous /srv/tenant-a et nomme son répertoire de projet work :

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

Claude Code écrit les transcriptions de la session dans /srv/tenant-a/projects/work/ et sa mémoire automatique dans /srv/tenant-a/projects/work/memory/, quel que soit le répertoire de travail.

Trois règles s'appliquent lorsque vous le définissez :

• Définissez aussi CLAUDE_CONFIG_DIR : le nom ne varie pas avec le répertoire de travail, donc sous le ~/.claude par défaut, il fusionnerait les transcriptions et la mémoire automatique de chaque projet dans un seul répertoire. Claude Code ignore CLAUDE_CODE_PROJECT_DIR_NAME lorsque CLAUDE_CONFIG_DIR n'est pas défini.
• Utilisez 1-64 lettres, chiffres, tirets ou traits de soulignement : n'utilisez pas un nom de périphérique Windows tel que con. Claude Code ignore toute autre valeur et utilise le nom dérivé.
• Définissez-le dans l'environnement shell qui démarre claude : Claude Code le lit une seule fois au démarrage à partir de cet environnement, donc un bloc env dans un fichier de paramètres ne peut pas le définir.

Une fois que vous avez nommé le répertoire de projet d'un répertoire de configuration, continuez à lancer avec ce nom. Si vous démarrez Claude Code avec le même CLAUDE_CONFIG_DIR mais sans CLAUDE_CODE_PROJECT_DIR_NAME, il lit et écrit à nouveau le répertoire dérivé. Les sessions stockées sous votre nom restent sur le disque : appuyez sur Ctrl+A dans le sélecteur de session pour lister les sessions de chaque répertoire de projet sous ce répertoire de configuration, celui épinglé inclus, et quelle que soit la façon dont vous lancez, claude --resume <session-id> trouve une session stockée sous l'un ou l'autre nom.

Voir aussi

Ces pages couvrent les mécaniques de session et de parallélisme connexes :

• Worktrees : exécuter des sessions parallèles isolées sur des branches séparées
• Points de contrôle : rembobiner le code et la conversation à un point antérieur
• Fenêtre de contexte : ce qui remplit le contexte et ce qui survit à la compaction
• Mode non interactif : comportement de la session sous claude -p