Claude Code : sessions, contexte et checkpoints pour reprendre sans repartir de zéro

Une session Claude Code est une conversation enregistrée, rattachée à un répertoire de projet, que vous pouvez quitter et reprendre. Cette page vous apprend à la piloter dans la durée : la reprendre par son nom ou son identifiant, savoir précisément ce que la reprise restaure et ce qu'elle laisse derrière, gérer la fenêtre de contexte quand elle se remplit, et revenir en arrière avec /rewind. Elle insiste sur un point que la plupart des présentations oublient : les checkpoints ne rattrapent pas tout, et connaître leurs angles morts décide de la façon dont vous travaillez.

Ce que vous allez apprendre

• Reprendre une session par son nom, son identifiant ou le sélecteur
• Distinguer ce qu'une reprise restaure de ce qu'il faut repasser en ligne de commande
• Gérer la fenêtre de contexte avec /context, /compact et /clear
• Revenir en arrière avec /rewind, et reconnaître ses angles morts
• Brancher une session pour explorer une autre piste sans perdre la première

Prérequis

• Claude Code installé, et au moins une session déjà menée sur lab-claude
• Le rituel de contrôle en place (voir mode plan, diff et validations)
• Un dépôt sous git, ce qui n'est pas une préférence de style ici mais une condition de récupération

Où vivent vos sessions, concrètement

Une session est un fichier sur votre disque. Claude Code enregistre la conversation en continu, au format JSONL, dans :

~/.claude/projects/<projet>/<identifiant-de-session>.jsonl

Le nom <projet> dérive du chemin du répertoire de travail, dont les caractères non alphanumériques sont remplacés par des tirets. Chaque ligne est un objet JSON décrivant un message, un appel d'outil ou une entrée de métadonnées.

Ne parsez pas ces fichiers. Le format est interne et change d'une version à l'autre : un script qui les lit directement casse à la première mise à jour. Pour exploiter une session depuis un script, passez par /export, par claude -p --resume <id> --output-format json, ou par le champ transcript_path que reçoivent les hooks.

Ces fichiers ne vivent pas éternellement. Le balayage de rétention les supprime par défaut environ trente jours après la dernière écriture. Le réglage cleanupPeriodDays allonge ce délai si vous en avez besoin, et cette valeur gouverne aussi les instantanés de fichiers des checkpoints, ce qui aura son importance plus bas.

Comment reprendre une session Claude Code ?

Cinq entrées mènent à une session existante, et le choix dépend de ce que vous savez d'elle.

Commande	Ce qu'elle fait
claude --continue	rouvre la conversation la plus récente du répertoire courant
claude --resume	ouvre le sélecteur de sessions
claude --resume <nom>	reprend directement la session portant ce nom
claude --resume <id>	reprend par identifiant, depuis n'importe quel répertoire
/resume	change de conversation sans quitter la session en cours

Glissez pour voir

La reprise par identifiant mérite une note : Claude Code cherche d'abord dans le projet courant et ses worktrees git, puis dans tous les autres projets de la machine. Vous pouvez donc reprendre depuis ailleurs une session démarrée ailleurs.

Les sessions `-p` sont invisibles dans le sélecteur

Une session créée par claude -p ou par l'Agent SDK n'apparaît ni dans le sélecteur, ni dans claude --continue. C'est délibéré, pour que vos exécutions scriptées ne polluent pas votre historique interactif.

Vous pouvez toujours la reprendre en passant son identifiant à claude --resume <id>. Et si vous voulez explicitement les inclure, la forme claude -p --continue les prend en compte.

Nommez vos sessions, surtout si vous en menez plusieurs

Un nom transforme une liste de conversations anonymes en quelque chose de navigable, et il devient un identifiant de reprise.

claude -n auth-refactor          # à la création

En cours de session, /rename auth-refactor fait la même chose et affiche le nom sur la barre de saisie. Depuis le sélecteur, Ctrl+R renomme la ligne sélectionnée. Accepter un plan en mode plan attribue par ailleurs un titre généré, si vous n'avez rien nommé.

Le sélecteur se pilote au clavier, et trois raccourcis évitent de le refermer frustré : Ctrl+A élargit à tous les projets de la machine, Ctrl+W à tous les worktrees du dépôt, Ctrl+B filtre sur la branche git courante. Space prévisualise le contenu de la session surlignée.

Ce qu'une reprise restaure, et ce qu'elle ne restaure pas

C'est la section à retenir de cette page. Une reprise ne remet pas la session dans l'état exact où vous l'aviez laissée, et la différence explique la plupart des surprises.

Restauré	Non restauré
l'historique complet, appels d'outils et résultats compris	les serveurs passés par --mcp-config
le modèle utilisé par la session	les réglages passés par --settings
l'agent si la session a démarré avec --agent	les plugins passés par --plugin-dir
le mode de permission, selon la façon dont vous reprenez	le modèle de repli --fallback-model
un objectif encore actif	les répertoires ajoutés par --add-dir
les tâches planifiées non expirées	les tâches Bash et les surveillances en arrière-plan

Glissez pour voir

La colonne de droite se résume en une phrase : ce que vous aviez passé en arguments de ligne de commande, il faut le repasser. En revanche, les fichiers de réglages habituels, settings.json et settings.local.json, sont relus au démarrage : ce qui vit dedans n'a pas besoin d'être répété.

Deux subtilités valent d'être connues. Un outil qui tournait encore quand le processus précédent s'est arrêté, par exemple lors d'un plantage, ne reprend pas et ne rejoue pas : Claude continue sans son résultat. Et le mode de permission n'est pas restauré de la même façon selon l'entrée : une reprise par claude --continue depuis un terminal le restaure, alors qu'une session choisie dans le sélecteur repart dans le mode qu'aurait une session neuve. Le mode bypassPermissions, lui, n'est jamais restauré automatiquement, ce qui est une bonne chose.

Reprendre une longue session : le dialogue de résumé

Sur les plans Pro et Max, quand vous reprenez une session inactive depuis plus d'une heure et pesant plus de 100 000 tokens, Claude Code ouvre un dialogue avant votre premier message. Le cache de prompt a expiré entre-temps, donc la prochaine requête retraitera l'historique une fois de toute façon, quelle que soit votre réponse.

Option	Ce qu'elle fait	Contrepartie
Reprendre depuis le résumé	lance un /compact immédiat, remplace l'historique par un résumé, vos derniers échanges et jusqu'à cinq fichiers récemment lus	moins cher à chaque requête ensuite, mais ce que le résumé omet n'est plus dans le contexte
Reprendre la session telle quelle	charge la conversation inchangée	tout reste disponible, à un coût par requête qui croît avec la taille
Ne plus demander	reprend en entier et supprime le dialogue à l'avenir	vous perdez le point de décision

Glissez pour voir

Que faire quand le contexte se remplit ?

Trois commandes, trois intentions différentes, et les confondre coûte soit du contexte utile, soit de l'argent.

Commande	Intention
/context	regarder ce qui occupe la fenêtre avant de décider quoi que ce soit
/compact [consignes]	remplacer l'historique par un résumé, éventuellement orienté par vos consignes
/clear	repartir à vide, la conversation précédente restant enregistrée

Glissez pour voir

Le réflexe utile est de commencer par /context. Une session qui rame n'est pas toujours une session trop longue : ce peut être un CLAUDE.md devenu énorme, une skill qui charge trop, ou un résultat d'outil volumineux resté dans l'historique. Compacter sans regarder revient à traiter un symptôme sans en connaître la cause.

/compact accepte des consignes, et c'est sous-employé. /compact garde le plan validé et les décisions d'architecture, oublie les traces de debug produit un résumé bien plus utile qu'un compactage aveugle.

`/clear` n'efface pas la conversation

/clear enregistre la conversation précédente avant de repartir à vide. Vous la retrouvez avec /resume, ou, dans le même processus Claude Code, via l'entrée dédiée en tête du menu de rembobinage.

Autrement dit, /clear n'est pas une perte : c'est une mise de côté.

Comment revenir en arrière avec les checkpoints ?

Claude Code crée un checkpoint à chaque prompt que vous envoyez. Il capture l'état de votre code avant ce prompt, et conserve les instantanés de fichiers pour les cent checkpoints les plus récents de la session. Ces checkpoints sont enregistrés avec la conversation : vous pouvez donc encore rembobiner après avoir repris une session.

Deux façons d'ouvrir le menu :

1. La commande explicite

   /rewind

2. Ou le raccourci, quand la zone de saisie est vide

   Appuyez deux fois sur Esc. Si la zone contient du texte, le double Esc efface ce texte au lieu d'ouvrir le menu. Le texte effacé part dans l'historique de saisie : Haut le rappelle une fois sorti du menu.

Le menu liste chaque prompt que vous avez envoyé pendant la session. Vous choisissez un point, puis une action :

Action	Effet
Restaurer le code et la conversation	revient sur les deux à ce point
Restaurer la conversation	rembobine la conversation, garde le code actuel
Restaurer le code	annule les modifications de fichiers, garde la conversation
Résumer à partir d'ici	compresse la conversation vers l'avant, libère du contexte
Résumer jusqu'ici	compresse ce qui précède, garde les messages suivants intacts

Glissez pour voir

Les deux options de restauration de code n'apparaissent que si le checkpoint sélectionné a des modifications de fichiers à annuler. Après une restauration de conversation, le prompt d'origine revient dans la zone de saisie : vous pouvez le renvoyer tel quel ou le corriger, ce qui en fait un excellent outil de reformulation.

Ce que les checkpoints ne rattrapent pas

C'est le point le plus important de cette page, et le plus mal connu. Un checkpoint suit les modifications faites par les outils d'édition de fichiers de Claude. Tout le reste lui échappe.

Angle mort	Conséquence
Commandes Bash	un rm, un mv, un cp lancé par Claude n'est pas suivi et ne se rembobine pas
Subagents	les modifications d'un subagent ne sont généralement pas restaurées, y compris celles d'une skill forkée qui tourne en arrière-plan, ce qui est son défaut
Modifications externes	ce que vous éditez hors de Claude Code, ou depuis une autre session, n'est pas capturé
Liens symboliques et liens durs	ces chemins sont ignorés à la restauration, avec un avertissement Restored the code, but skipped N files
Instantanés expirés	passé le délai de rétention, un rembobinage peut échouer sur No files were restored

Glissez pour voir

La seule exception notable concerne une skill forkée exécutée au premier plan : elle modifie l'arbre de travail pendant votre propre tour, donc le rembobinage restaure bien ses modifications. Une skill forkée en arrière-plan, qui est le comportement par défaut, échappe au dispositif.

Git reste la frontière de récupération

Les checkpoints sont un filet de session, pas un système de version. La documentation le dit explicitement, et les angles morts ci-dessus expliquent pourquoi : dès qu'un subagent travaille en arrière-plan ou qu'une commande shell touche le disque, /rewind ne vous ramènera pas en arrière.

La discipline qui en découle est simple et vaut pour tout le parcours : committez avant de lancer une tâche longue, surtout si elle délègue à des subagents ou si elle passe par des commandes shell. Un git stash ou un commit de travail coûte dix secondes et couvre exactement ce que les checkpoints ne couvrent pas.

Brancher plutôt que casser

Quand vous voulez essayer autre chose sans perdre le chemin parcouru, ne rembobinez pas : branchez. /branch copie la conversation jusqu'au point courant et vous bascule dans la copie, en laissant l'originale intacte et présente dans le sélecteur.

/branch essai-streaming

Depuis la ligne de commande, la même idée s'écrit claude --continue --fork-session. La différence compte : /branch copie la transcription et bascule le processus en cours dans la nouvelle, alors qu'un fork depuis la ligne de commande démarre un processus séparé.

Cette distinction a une conséquence pratique sur les permissions. Les autorisations accordées « pour cette session » suivent dans une branche créée par /branch, puisque c'est le même processus ; elles ne suivent pas dans un --fork-session, où vous devrez réapprouver.

Un subagent ou une commande Bash en cours d'exécution continue de tourner, et sa sortie apparaît dans la branche où vous venez de basculer, pas dans la session d'origine.

Pièges courants

Symptôme	Cause probable	Correction
Le double Esc n'ouvre pas le menu	la zone de saisie contient du texte, le raccourci l'efface d'abord	videz la zone, ou lancez /rewind
/rewind n'annule pas un fichier supprimé	la suppression est passée par une commande Bash, non suivie	git restore, ou git checkout du fichier
Restored the code, but skipped N files	des chemins sont des liens symboliques ou durs	annulez l'édition à la main, ou demandez à Claude de la renverser
No files were restored	les instantanés ont expiré au balayage de rétention	augmentez cleanupPeriodDays pour l'avenir, récupérez par git pour le passé
Une session -p est introuvable dans le sélecteur	les sessions non interactives en sont exclues	reprenez par identifiant avec claude --resume <id>
Un serveur MCP manque après une reprise	--mcp-config n'est pas restauré	repassez le drapeau, ou déclarez le serveur dans un fichier de réglages

Glissez pour voir

Checklist de fin de guide

• Je nomme mes sessions quand j'en mène plusieurs en parallèle
• Je sais que les arguments de ligne de commande ne sont pas restaurés
• Je lance /context avant de compacter
• Je sais ouvrir /rewind et distinguer ses cinq actions
• Je committe avant toute tâche qui délègue à des subagents

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Une session est un fichier JSONL dans ~/.claude/projects/, supprimé au bout d'environ trente jours par défaut. Ne le parsez pas, son format est interne.
• Une reprise restaure la conversation, le modèle et l'agent, mais pas ce que vous aviez passé en arguments : --mcp-config, --settings, --plugin-dir, --add-dir.
• /context avant /compact : une session lourde n'est pas toujours une session longue.
• /clear n'efface rien : la conversation précédente reste reprenable.
• Un checkpoint est créé à chaque prompt, et les instantanés couvrent les cent derniers.
• Les checkpoints ignorent les commandes Bash, les subagents en arrière-plan et les liens symboliques. Git reste la frontière de récupération.
• /branch explore sans casser : la session d'origine reste intacte et reprenable.

Pour aller plus loin

• Subagents pour isoler le contexte : la délégation dont les modifications échappent justement aux checkpoints.
• Mode headless et intégration CI : les sessions non interactives, invisibles dans le sélecteur, et comment les reprendre.
• Dépannage avancé : le diagnostic quand une session dérive sans cause évidente.

×

📖 Voir la documentation →