Récupérer Claude Code : mode sans échec, /cd et modèles de secours

Des ressources pratiques sur le travail avec des agents : documentation Ailoot.

Quels outils Claude Code propose-t-il pour récupérer une session ?#

Auparavant, lorsque Claude Code se comportait bizarrement — roue de chargement infinie, plantage au démarrage, agent qui ignore les règles de CLAUDE.md, hook qui ne se déclenche pas sans avertissement — il n’y avait qu’une seule issue : commenter manuellement des sections de .claude/settings.json, désactiver les serveurs MCP un par un ou, dans le pire des cas, supprimer ~/.claude et réinstaller. Dans un cas décrit, ~/.claude a été supprimé et la configuration des serveurs MCP, qui avait demandé une heure et demie de travail, a été perdue. On a découvert par la suite qu’une ligne dans CLAUDE.md était en cause et qu’on aurait pu la trouver en 10 secondes — mais cela n’est devenu évident qu’après une récupération complète.

En juin 2026, Anthropic a déployé trois mécanismes qui changent la donne. En bref, voici ce qui est arrivé et quand :

Ci-dessous, chaque mécanisme est expliqué étape par étape, ainsi que l’ordre dans lequel les appliquer lorsqu’une session Claude Code déraille.

Qu’est-ce qui provoque le plus souvent des pannes dans Claude Code ?#

Dans l’exemple décrit, CLAUDE.md comptait au départ 80 lignes — et a fonctionné pendant un mois. Au cours du deuxième mois, on a constaté que, chaque semaine, Claude finissait par enfreindre toutes les règles établies : toucher à .env, exécuter git push --force, fouiller dans node_modules. Ce n’était pas malveillant : il avait simplement oublié. Une fois, .gitignore a été supprimé et la raison n’était pas évidente. Ce scénario est expliqué plus en détail dans le guide sur CLAUDE.md.

Quand CLAUDE.md dépasse 400 lignes, il commence à causer des problèmes en silence : il occupe une part importante de la fenêtre de contexte dès le démarrage de la session et dilue les instructions importantes parmi les consignes secondaires. Claude lit toujours le fichier, du moins en théorie, si bien qu’en apparence « les règles sont là, mais elles ne fonctionnent pas » — signe typique d’un contrat surchargé.

Les hooks sont la deuxième source de problèmes la plus courante. Les Claude Code hooks ont une particularité qu’Anthropic ne met pas en avant.

Autrement dit, sys.exit(1) dans un hook Python (ou tout autre « échec avec erreur » conventionnel sous Unix) n’arrêtera pas Claude. Seul le code 2 est bloquant. Dans le cas décrit, le hook était considéré comme une « interdiction stricte », mais en pratique, il enregistrait une plainte et autorisait l’action.

Les serveurs MCP constituent la troisième couche et peuvent eux aussi tomber en panne, à leur manière.

Le symptôme est souvent le même : les commandes MCP sont disponibles, mais renvoient failed sans trace de pile. Pour en savoir plus sur la configuration de MCP et l’ajout de serveurs avec claude mcp add, consultez le guide dédié.

La quatrième source de problèmes est la hiérarchie à trois niveaux de settings.json. On trouve ~/.claude/settings.json (niveau utilisateur), .claude/settings.json à la racine du projet (projet), .claude/settings.local.json (local) et, éventuellement, les paramètres gérés par un administrateur d’entreprise. Ces paramètres sont combinés selon des règles de priorité. Si quelqu’un ajoute un serveur MCP au niveau du projet alors qu’une entrée similaire avec une configuration de lancement différente existe au niveau utilisateur, un conflit silencieux survient, donnant l’impression que « Claude Code est en panne ».

Comment fonctionne --safe-mode et que désactive-t-il ?#

Voici le texte original d’Anthropic dans les notes de version de v2.1.169 :

Anthropic apporte une précision dans la documentation sur la configuration des modèles :

C’est un outil de diagnostic, pas un « environnement propre ». Le mode sans échec aide à répondre à une question : le problème vient-il du comportement de Claude Code par défaut, ou des personnalisations ajoutées ? Cela fait partie de l’ingénierie du contexte : gérer ce que Claude voit ou ne voit pas à un moment donné. Si tout fonctionne en mode sans échec, il est clair qu’il faut vérifier les couches par recherche binaire. Si le problème persiste, il vient de l’installation elle-même, de l’autorisation, du réseau ou de l’infrastructure ; il est alors judicieux d’examiner claude doctor et les journaux.

Ce que le mode sans échec désactive (liste officielle d’Anthropic — 5 couches principales) :

• CLAUDE.md à tous les niveaux (utilisateur / projet)
• Plugins
• Skills
• Hooks
• Serveurs MCP

Ce qui continue de fonctionner :

• L’autorisation (votre session OAuth ou votre clé API)
• Le choix du modèle (--model sonnet, --model opus)
• Les outils intégrés (Read, Write, Bash, Grep, etc.)
• Les permissions
• L’état de git
• Les noms de répertoires

Un détail important : le mode sans échec ne désactive pas les paramètres gérés par un administrateur d’entreprise ou les politiques d’entreprise. Si vous travaillez dans une équipe où Bedrock GovCloud ou une configuration MDM définit availableModels, ces restrictions restent en vigueur : le mode sans échec désactive uniquement vos personnalisations, pas les politiques d’entreprise.

Comment isoler une couche et trouver le responsable en 60 secondes ?#

Voici un scénario de diagnostic à utiliser lorsque Claude Code « n’écoute plus ». La version minimale pour toutes les commandes ci-dessous est Claude Code v2.1.169. Si votre version est antérieure, commencez par la mettre à jour (npm update -g @anthropic-ai/claude-code ou avec l’installateur natif d’Anthropic).

1. Ouvrez le même dossier que celui où le problème est survenu.
2. Exécutez claude --safe-mode.
3. Si Claude démarre correctement, vérifiez votre demande initiale. A-t-il répondu comme prévu ? Une des couches est alors en cause. Passez à l’étape 4.
4. Si le problème persiste en mode sans échec, ne touchez pas aux configurations. Commencez par exécuter claude doctor ; vérifiez l’authentification, la version et les installations conflictuelles.

Dès que le mode sans échec démarre correctement, réactivez les couches une par une, en commençant par la plus suspecte. Voici l’ordre établi d’après l’expérience décrite :

1. CLAUDE.md. Exécutez claude sans le mode sans échec, mais renommez temporairement le fichier : mv CLAUDE.md CLAUDE.md.bak. Si tout fonctionne, le fichier est en cause. Vous pouvez ensuite effectuer une recherche binaire : conservez la moitié des lignes et vérifiez.
2. Hooks. Ouvrez .claude/settings.json et remplacez temporairement le contenu de la section hooks par []. Redémarrez claude. Le problème a-t-il disparu ? Un des hooks est en cause. Réactivez-les un par un.
3. Serveurs MCP. De même, dans ~/.claude.json ou .claude/settings.json, remplacez temporairement la section mcpServers par un objet vide, redémarrez et vérifiez.
4. Skills. Déplacez .claude/skills/ dans un dossier temporaire. Lancez Claude et vérifiez.

« Renommer temporairement » signifie que les fichiers ne sont pas supprimés pendant le diagnostic. mv ou git stash vous permettent de tout restaurer en une commande si cette couche n’est finalement pas en cause.

Comment changer de dossier de travail avec /cd sans perdre le contexte ?#

Voici l’entrée des notes de version de v2.1.169 du 8 juin :

Pourquoi est-ce utile pour résoudre un problème ? Imaginons que vous soyez dans le dossier du projet ~/work/myapp et que Claude Code se comporte bizarrement. Auparavant, pour vérifier « s’il fonctionne tout court », il fallait fermer la session, changer de dossier et redémarrer. Vous perdiez le contexte, l’historique et le cache de prompt déjà préchauffé. Maintenant :

# In the same session:
/cd ~/sandbox/test

Claude passe au nouveau dossier et lit son CLAUDE.md (s’il existe) comme un message, et non comme un remplacement du prompt système : le cache est donc préservé. Si tout fonctionne dans ~/sandbox/test, le problème vient de la configuration de ~/work/myapp.

Le 12 juin, v2.1.176 a corrigé une régression gênante : /cd affichait l’ancienne branche git jusqu’au redémarrage complet. Si vous avez une version antérieure, mettez-la à jour ou ignorez simplement git status pendant les premiers messages après le changement de dossier : l’information se mettra à jour.

Comment configurer des modèles de secours pour une erreur 529 ?#

Dans le scénario décrit, une tâche longue s’exécute avec Opus dans un projet une fois par semaine ; après 10 minutes, l’API renvoie 529 Overloaded et la session plante. Auparavant, il fallait attendre ou passer manuellement à Sonnet avec --model sonnet, en perdant tout le contexte préchauffé. Dans un grand dossier business/ avec une configuration de second cerveau, cela représente environ vingt minutes de travail. Il existe désormais un mécanisme adapté.

Voici la citation exacte de la documentation officielle :

Et voici séparément le fonctionnement de la chaîne :

Il existe deux façons de le configurer. Avec la CLI :

claude --fallback-model sonnet,haiku

Dans ~/.claude/settings.json :

{
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Une précision concerne les limites de débit. Anthropic ne fait volontairement pas passer les erreurs 429 dans la chaîne, afin d’éviter de contourner la limite de requêtes en basculant vers le modèle suivant. Le modèle de secours est utilisé uniquement lorsque le modèle principal est surchargé, indisponible ou renvoie une erreur serveur non réessayable (par exemple, 529 Overloaded). Les limites de débit suivent la logique normale de nouvelle tentative et de temporisation progressive.

Autre précision : le 12 juin, v2.1.174 a corrigé une régression : la compaction ne tenait pas compte de --fallback-model. Si vous avez une longue session qui se compacte pendant une surcharge, avant ce correctif le modèle de secours n’était pas appelé. Si vous travaillez avec de longues sessions (/compact, /loop pendant la nuit), passez au moins à v2.1.174.

Que corriger si CLAUDE.md, un hook, MCP ou un skill est en cause ?#

Voici des stratégies précises pour chaque couche.

Si CLAUDE.md est en cause

Ouvrez le fichier et vérifiez sa taille. D’après l’expérience décrite, limitez le fichier CLAUDE.md actif à 200 lignes maximum ; déplacez le reste dans des routeurs et des documents complémentaires à côté du projet (la structure complète du second cerveau est présentée dans le guide sur le second cerveau). Au-delà de 400 lignes, il est presque certainement en cause. Voici les étapes :

1. Faites une sauvegarde : cp CLAUDE.md CLAUDE.md.full.
2. Revenez à un modèle court et fonctionnel. Vous en trouverez un prêt à l’emploi dans le guide « Comment configurer CLAUDE.md ».
3. Redémarrez Claude Code. Vérifiez.
4. Si cela fonctionne, rétablissez les règles par petits blocs de 10–20 lignes, en vérifiant après chaque bloc.
5. Trouvez le bloc qui perturbe le comportement. Réécrivez-le sous forme de hook avec le bon code de sortie (les codes de sortie des hooks sont traités dans la sous-section suivante de ce H2).

Si un hook est en cause

La question principale est de savoir si le code de sortie est correct. Les hooks de Claude Code utilisent les valeurs suivantes :

• Exit 0 — tout va bien ; l’action se poursuit.
• Exit 1 — une erreur, mais non bloquante. Claude continue comme si de rien n’était.
• Exit 2 — une erreur bloquante. C’est le seul code qui arrête réellement l’action.

Si vous avez écrit sys.exit(1) ou exit 1 dans un hook shell en pensant bloquer l’action, dans Claude Code ce code sert à consigner un avertissement sans arrêter l’action. Remplacez-le par 2. Pour en savoir plus sur les hooks et leur configuration sans ce piège, consultez le guide dédié.

Un autre cas fréquent est un hook qui renvoie un JSON invalide sur stdout. Claude Code analyse la réponse du hook comme du JSON ; si elle contient du texte parasite (un journal, un indicateur de progression, un emoji), le hook est considéré comme ayant échoué et l’action se poursuit. Règle à suivre : stdout ne contient que du JSON ; tout le reste va dans stderr.

Le troisième cas est celui d’un hook qui lit des éléments de ~/.claude/ masqués par le mode sans échec. C’est un scénario normal. Ne corrigez pas le problème en modifiant le hook : vérifiez plutôt os.environ.get('CLAUDE_CODE_SAFE_MODE') au début et terminez avec le code 0.

Si un serveur MCP est en cause

Symptômes : les commandes MCP sont disponibles, mais renvoient failed sans trace de pile claire. Étapes :

1. Exécutez claude mcp list : quels serveurs sont définis ?
2. Désactivez les serveurs un par un dans ~/.claude.json : renommez la clé claude-server-A en _claude-server-A (cela la désactive sans la supprimer).
3. Redémarrez claude. Vérifiez quels appels fonctionnent.
4. Une fois le serveur responsable trouvé, vérifiez son journal : claude mcp logs <name>.
5. S’il s’agit d’un serveur tiers (@modelcontextprotocol/server-postgres ou équivalent), vérifiez s’il existe une version récente. L’écosystème MCP est encore très instable ; les serveurs cessent régulièrement de fonctionner à la suite des mises à jour de Claude Code.

Si vous constatez « des plantages au démarrage, uniquement avec deux MCP », comparez le comportement en mode sans échec, sans MCP.

Si un skill est en cause

Un skill comprend SKILL.md et du code dans .claude/skills/<name>/. Symptômes : Claude ignore le skill, l’applique au mauvais moment ou l’applique mais produit des résultats inutilisables. Étapes :

1. Ouvrez SKILL.md. Vérifiez sa description : elle doit compter 1–2 phrases et préciser quand utiliser le skill. Si elle indique « un assistant universel pour tout », Claude ne sait pas quand le lancer.
2. Vérifiez qu’elle ne contredit pas CLAUDE.md. Si CLAUDE.md dit « toujours écrire des tests », mais que la description du skill dit « utiliser pour le prototypage rapide sans tests », il y a un conflit.
3. Si le skill utilise des commandes externes (npm, python, git), vérifiez qu’elles sont accessibles dans le PATH système. Un skill a son propre environnement minimal.

Si le mode sans échec ne suffit pas : diagnostiquer et préserver avant réparation#

Supprimer l’état utilisateur n’est pas un raccourci de diagnostic. Identifiez la panne avec les contrôles ci-dessous ; si elle reste inconnue, préservez les preuves et poursuivez l’enquête. Toute réparation commence par une sauvegarde vérifiée et conserve compte et identité du stockage d’identifiants. Ordre :

1. claude doctor — diagnostics automatiques. Anthropic écrit dans sa documentation :

2. Vérifiez les installations conflictuelles. Beaucoup de personnes ont à la fois une version globale npm et l’installateur natif :

3. Vérifiez si ANTHROPIC_API_KEY intercepte votre session OAuth. C’est une cause fréquente du problème « rien ne fonctionne, la clé a expiré » :

Solution : exécutez unset ANTHROPIC_API_KEY dans la session shell en cours ou retirez-la de ~/.zshrc / ~/.bashrc.

4. Réparez seulement l’installation diagnostiquée après préservation de tout l’état utilisateur. Un mode sans échec en panne ou un doctor indécis n’impose pas la suppression des données. Arrêtez sessions Claude et autres rédacteurs avant une sauvegarde cohérente. Gardez même compte Unix, HOME, stockage d’identifiants système et compte Anthropic ; ne changez ni clé ni identité.

L’exemple suivant exige Linux et GNU tar. Sur macOS ou Windows, utilisez un outil préservant ACL, attributs étendus, liens et métadonnées, puis vérifiez la restauration ; ne supposez pas les options GNU compatibles. L’archive contient identifiants et transcriptions : gardez-la privée et hors des dépôts.

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

Toutes les commandes doivent réussir. L’archive couvre tout .claude, sessions ignorées ou non suivies et état des plugins compris, ainsi que .claude.json, pas seulement les réglages Git. Si un chemin est un lien ou si les données sont ailleurs, arrêtez et incluez la cible résolue dans la même sauvegarde vérifiée : un lien seul ne sauvegarde pas sa cible. Keychain et autres stockages externes d’identifiants ne sont pas inclus ; préservez-les en place.

Si le diagnostic identifie précisément l’installation locale historique comme copie conflictuelle, déplacez seulement celle-ci dans le dossier privé au lieu de supprimer configuration et sessions :

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

Ne retirez une installation npm que si elle est diagnostiquée comme conflictuelle et si vous souhaitez garder la native. Utilisez ensuite l’installateur documenté, sans supprimer .claude ni .claude.json :

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Sous Windows, la commande native reste :

irm https://claude.ai/install.ps1 | iex

Restauration séparée. Arrêtez les rédacteurs, vérifiez la somme et extrayez dans un dossier de récupération vide, puis comparez avant utilisation. Pour rétablir l’installation déplacée, confirmez d’abord l’absence de $HOME/.claude/local, puis déplacez $backup_dir/legacy-local à ce chemin exact. Ne restaurez un réglage diagnostiqué qu’après préservation du remplacement actuel ; n’écrasez pas tout l’arbre. Sessions, MCP et identité d’origine restent préservés. Git seul ne couvre ni transcriptions ignorées/non suivies, ni identifiants, ni métadonnées.

Que NE faut-il PAS faire lorsque Claude Code est en panne ?#

Ne modifiez pas les clés avant le diagnostic

Dans 90% des cas, « l’autorisation ne fonctionne pas » signifie que ANTHROPIC_API_KEY intercepte l’abonnement, qu’un hook a un bug d’interface ou qu’un MCP a échoué. Faire tourner les clés ne corrigera aucun de ces problèmes, mais entraînera une heure d’interruption supplémentaire : il faudra révoquer l’ancienne clé, en créer une nouvelle, mettre à jour la signature de CI avec celle-ci et actualiser les variables en production. Commencez par exécuter claude --safe-mode. Cela fonctionne-t-il ? Le problème vient alors des personnalisations ; inutile de toucher aux clés.

N’effectuez pas de réinitialisation complète avant d’essayer le mode sans échec

Le mode sans échec fournit un environnement isolé en 1 seconde. Supprimer .claude peut détruire sessions, configuration MCP et état non suivi. Diagnostiquez, vérifiez une sauvegarde privée puis ne déplacez réversiblement que l’installation ou la couche de configuration réellement en cause.

Ne paniquez pas à cause d’une erreur d’interface dans un hook

Avant de corriger quoi que ce soit, vérifiez si le hook s’est réellement exécuté (en examinant un journal dans stderr ou en affichant explicitement un message), au lieu de vous fier à l’indicateur visuel.

N’augmentez pas le code de sortie d’un hook avant d’en corriger la logique

Lorsque votre hook bloquant ne bloque pas, la tentation est grande de définir exit 2 et de considérer le problème réglé. C’est un correctif qui fonctionne, mais il masque un autre problème : si le blocage n’a pas fonctionné pendant un mois, tout ce que le hook devait interdire a pu passer. Consultez d’abord le journal git pour déterminer exactement ce qui a échappé au contrôle. Ajoutez ensuite le blocage. Sinon, le fait de fermer la porte ne défait pas ce qui s’est passé auparavant.

Ne modifiez pas le CLAUDE.md de production sans protection du mode sans échec

Dans le cas décrit, vous modifiez CLAUDE.md, Claude commence à se comporter bizarrement, puis git diff révèle que quelqu’un a également ajouté un serveur MCP et un hook au dépôt ce soir-là. Vous accusez votre modification, l’annulez, mais Claude continue de se comporter bizarrement. Règle : avant git revert, exécutez claude --safe-mode. Si le problème persiste en mode sans échec, votre modification n’y était pour rien ; inutile de l’annuler.

Ne croyez pas que « Claude répare lui-même son MCP »

Un cas typique : vous demandez à Claude « d’ajouter un outil particulier au serveur MCP », Claude réécrit une configuration qui fonctionnait, tout tombe en panne, puis Claude passe plusieurs tours à déboguer les dégâts qu’il a causés — tout en consommant le quota de la session. Lorsque MCP est en panne, récupérez la configuration manuellement ; ne laissez pas l’agent s’en charger. Une partie de son arsenal d’outils fonctionne également avec MCP, et un MCP en panne signifie un diagnosticien en panne.

Que faire après avoir réparé le problème ?#

Après avoir analysé l’incident, ne reprenez pas le travail immédiatement. Commencez par ajouter des mesures de prévention pour éviter qu’il ne se reproduise. Un second cerveau (le dossier business/ avec la structure du projet) et CLAUDE.md peuvent demander des heures de travail ; il est difficile de les restaurer manuellement, ce qui constitue une bonne raison de s’en prémunir. Ensemble minimal :

1. ~/.claude/settings.json avec permissions.disableBypassPermissionsMode: "disable" — une interdiction architecturale du mode contournement, afin qu’un lancement accidentel de --dangerously-skip-permissions ne puisse tout simplement pas fonctionner.
2. Des hooks pour Read(./env*), Bash(git push --force), Write(./node_modules/**) — des éléments à encadrer par des règles strictes, pas de simples souhaits.
3. Une configuration de bac à sable pour les longues exécutions autonomes (/loop, /schedule).
4. /compact avec vos propres règles pour déterminer ce qu’il faut supprimer du contexte, afin que Claude ne s’épuise pas lui-même.

Le schéma de protection complet en quatre couches figure dans le guide « Comment configurer Claude Code pour qu’il ne casse pas votre projet pendant la nuit ». L’un des guides traite de la prévention avant de lancer /loop ; l’autre, de la récupération après que /loop a déjà endommagé quelque chose. Un duo logique.

Ressources pratiques : documentation Ailoot.

Plus de ressources et d’outils : Ailoot.