Claude Code herstellen: veilige modus, /cd en fallback

Praktische materialen over werken met agents: Ailoot-documentatie.

Wat verandert er in Claude Code in juni 2026?#

Voorheen was er maar één uitweg wanneer Claude Code zich vreemd begon te gedragen—een eindeloze laadindicator, een crash bij het opstarten, de agent die regels in CLAUDE.md negeert, een hook die stilletjes niet afgaat: handmatig secties van .claude/settings.json in commentaar zetten, MCP-servers een voor een uitschakelen of, in het ergste geval, ~/.claude verwijderen en opnieuw installeren. In een beschreven geval werd ~/.claude verwijderd en ging de configuratie van de MCP-server, waaraan anderhalf uur was besteed, verloren. Later bleek één regel in CLAUDE.md de boosdoener te zijn, en die had in 10 seconden gevonden kunnen worden—maar dat werd pas duidelijk na een volledig herstel.

In juni 2026 introduceerde Anthropic drie mechanismen die dit scenario veranderen. Kort samengevat: wat kwam erbij en wanneer:

Hieronder wordt elk mechanisme stap voor stap uitgelegd, samen met de volgorde waarin je ze toepast wanneer een Claude Code-sessie ontspoort.

Waardoor loopt Claude Code het vaakst vast?#

In het beschreven voorbeeld werd CLAUDE.md aanvankelijk in 80 regels opgesteld en werkte het een maand lang. In de tweede maand werd merkbaar dat Claude eens per week alle ingestelde regels overtrad: .env aanraken, git push --force uitvoeren, in node_modules rondneuzen. Niet kwaadwillig—Claude was het gewoon vergeten. Een keer werd .gitignore verwijderd en was de reden niet meteen duidelijk. Dit scenario wordt uitgebreider behandeld in de gids voor CLAUDE.md.

Wanneer CLAUDE.md 400+ regels bevat, begint het stilletjes problemen te veroorzaken: het neemt bij het starten van de sessie een aanzienlijk deel van het contextvenster in en verdunt belangrijke instructies tussen secundaire instructies. Claude leest het bestand formeel nog steeds, waardoor het van buitenaf lijkt alsof “de regels er wel zijn, maar niet werken”—een typisch teken van een te omvangrijk contract.

Hooks zijn de op een na meest voorkomende bron. Claude Code hooks hebben een nuance die Anthropic niet benadrukt.

Dat betekent dat sys.exit(1) in een Python-hook (of een andere Unix-conventionele “mislukt met een fout”) Claude niet stopt. Alleen code 2 blokkeert. In het beschreven geval werd de hook als een “hard verbod” beschouwd, maar in de praktijk registreerde die een klacht en stond de actie toe.

MCP-servers vormen de derde laag en vallen ook op hun eigen manier uit.

Het symptoom ziet er vaak hetzelfde uit: MCP-opdrachten zijn beschikbaar, maar geven failed terug zonder traceback. Zie voor meer informatie over MCP configureren en servers toevoegen met claude mcp add de aparte gids.

De vierde bron is de hiërarchie van settings.json met drie niveaus. Je hebt ~/.claude/settings.json (gebruikersniveau), .claude/settings.json in de projecthoofdmap (project), .claude/settings.local.json (lokaal) en eventueel beheerde instellingen van een bedrijfsbeheerder. Ze worden gecombineerd volgens prioriteitsregels. Wanneer iemand op projectniveau een MCP-server toevoegt terwijl je op gebruikersniveau een vergelijkbare vermelding met een andere startconfiguratie hebt, ontstaat er een stil conflict dat eruitziet alsof “Claude Code kapot is”.

Hoe werkt --safe-mode en wat schakelt het uit?#

De oorspronkelijke formulering van Anthropic in de changelog van v2.1.169 luidt:

Anthropic licht dit toe in de documentatie over modelconfiguratie:

Dit is een diagnostisch hulpmiddel, geen “schone omgeving”. De veilige modus helpt één vraag te beantwoorden: ligt het probleem bij het standaardgedrag van Claude Code of bij de toegevoegde aanpassingen? Dit maakt deel uit van context engineering—beheren wat Claude op een bepaald moment wel en niet ziet. Als alles in de veilige modus werkt, is duidelijk dat je de lagen met een binaire zoekmethode moet controleren. Werkt het niet, dan ligt het probleem bij de installatie zelf, de autorisatie, het netwerk of de infrastructuur; dan is het zinvol om claude doctor en de logs te bekijken.

Wat de veilige modus uitschakelt (de officiële lijst van Anthropic—5 hoofdlagen):

• CLAUDE.md op alle niveaus (gebruiker / project)
• Plugins
• Skills
• Hooks
• MCP-servers

Wat blijft werken:

• Autorisatie (je OAuth-sessie of API-sleutel)
• Modelselectie (--model sonnet, --model opus)
• Ingebouwde tools (Read, Write, Bash, Grep enzovoort)
• Machtigingen
• Git-status
• Mapnamen

Een belangrijk detail: de veilige modus schakelt beheerde/policy-instellingen van een bedrijfsbeheerder niet uit. Als je werkt in een team waar Bedrock GovCloud of een MDM-configuratie availableModels instelt, blijven die beperkingen gelden—de veilige modus schakelt alleen je eigen aanpassingen uit, niet het bedrijfsbeleid.

Hoe isoleer je een laag en vind je de boosdoener in 60 seconden?#

Een diagnostisch scenario voor wanneer Claude Code “niet meer luistert”. De minimale versie voor alle onderstaande opdrachten is Claude Code v2.1.169. Is jouw versie ouder, werk dan eerst bij (npm update -g @anthropic-ai/claude-code of via het native installatieprogramma van Anthropic).

1. Open dezelfde map waar het misging.
2. Voer claude --safe-mode uit.
3. Als het probleemloos start, controleer dan je oorspronkelijke verzoek. Werkte het? Dan ligt de schuld bij een van de lagen. Ga naar stap 4.
4. Is het in de veilige modus nog steeds kapot, raak de configuraties dan niet aan. Voer eerst claude doctor uit; controleer auth, de versie en conflicterende installaties.

Zodra de veilige modus probleemloos start, schakel je de lagen een voor een in, te beginnen met de meest waarschijnlijke boosdoener. De volgorde op basis van de beschreven ervaring:

1. CLAUDE.md. Voer claude uit zonder veilige modus, maar hernoem het bestand tijdelijk: mv CLAUDE.md CLAUDE.md.bak. Werkt het dan, dan is dat bestand de oorzaak. Je kunt vervolgens een binaire zoekmethode gebruiken: behoud de helft van de regels en controleer.
2. Hooks. Open .claude/settings.json en zet tijdelijk [] in de sectie hooks. Start claude opnieuw. Werkt het dan? Dan is een van de hooks de boosdoener. Schakel ze een voor een in.
3. MCP-servers. Stel in ~/.claude.json of .claude/settings.json de sectie mcpServers tijdelijk op een leeg object in, start opnieuw en controleer.
4. Skills. Verplaats .claude/skills/ naar een tijdelijke map. Start op en controleer.

Wat “tijdelijk hernoemen” betekent: bestanden worden tijdens de diagnose niet verwijderd. Met mv of git stash kun je alles met één opdracht herstellen als die laag niet de boosdoener blijkt.

Hoe wissel je met /cd van werkmap zonder context te verliezen?#

Uit de changelog van v2.1.169 van 8 juni:

Waarom is dit handig bij het oplossen van problemen? Stel dat je in de projectmap ~/work/myapp zit en Claude Code zich vreemd gedraagt. Voorheen was de enige manier om te controleren “werkt het eigenlijk wel?” de sessie sluiten, naar een andere map gaan en opnieuw starten. Je verloor de context, geschiedenis en opgewarmde promptcache. Nu kun je:

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

Claude schakelt over naar de nieuwe map en leest de eventuele CLAUDE.md als een bericht, niet als vervanging van de systeemprompt—de cache blijft dus behouden. Als alles werkt in ~/sandbox/test, is duidelijk dat het probleem in de configuratie van ~/work/myapp zat.

Op 12 juni loste v2.1.176 een vervelende regressie op—/cd toonde de oude git-branch tot een volledige herstart. Is jouw versie ouder, werk dan bij of negeer git status gewoon voor de eerste paar berichten na het wisselen—het wordt vanzelf bijgewerkt.

Hoe configureer je fallbackmodellen voor een 529?#

In het beschreven scenario draait er eenmaal per week een lange taak op Opus in een project; na 10 minuten retourneert de API 529 Overloaded en crasht de sessie. Voorheen moest je wachten of handmatig naar Sonnet overschakelen met --model sonnet, waarbij je alle opgewarmde context verloor. In een grote map business/ met een second-brain-configuratie kost dat ongeveer twintig minuten werk. Nu is er een echte oplossing.

Het exacte citaat uit de officiële documentatie:

En daarnaast, hoe de keten werkt:

Je kunt dit op twee manieren configureren. Via de CLI:

claude --fallback-model sonnet,haiku

Via ~/.claude/settings.json:

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

Een aparte nuance betreft rate limits. Anthropic stuurt een 429-fout bewust niet door de keten, zodat je de verzoeklimiet niet kunt omzeilen door naar het volgende model over te schakelen. Fallback werkt alleen wanneer het primaire model overbelast of niet beschikbaar is, of een niet-opnieuw-probeerbare serverfout retourneert (bijvoorbeeld 529 Overloaded). Voor rate limits geldt de normale retrylogica met back-off.

Nog een nuance—op 12 juni loste v2.1.174 een regressie op: compaction hield geen rekening met --fallback-model. Als je een lange sessie hebt en die wordt gecompact terwijl het model overbelast is, werd het fallbackmodel vóór deze oplossing niet aangeroepen. Werk bij tot ten minste v2.1.174 als je met lange sessies werkt (/compact, /loop ’s nachts).

Wat moet je repareren wanneer CLAUDE.md, een hook, MCP of een skill de schuldige is?#

Concrete strategieën per laag.

Als CLAUDE.md de schuldige is

Open het bestand en controleer de omvang. Houd de actieve CLAUDE.md op basis van de beschreven ervaring op maximaal 200 regels; verplaats de rest naar routers en ondersteunende documenten naast het project (de volledige second-brain-structuur staat in de gids over het second brain). Met 400+ regels is het vrijwel zeker de boosdoener. Stappen:

1. Maak een back-up: cp CLAUDE.md CLAUDE.md.full.
2. Ga terug naar een kort werkend sjabloon. Een kant-en-klaar sjabloon staat in de gids “CLAUDE.md configureren”.
3. Start Claude Code opnieuw. Controleer.
4. Werkt het, herstel dan de regels in kleine blokken van 10–20 regels en controleer na elk blok.
5. Zoek het blok dat het gedrag verstoort. Herschrijf het als een hook met de juiste exitcode (exitcodes voor hooks worden behandeld in de volgende subsectie van deze H2).

Als een hook de schuldige is

De belangrijkste vraag is of de exitcode juist is. Claude Code-hooks gebruiken:

• Exit 0 — alles in orde; de actie gaat door.
• Exit 1 — een fout, maar niet-blokkerend. Claude gaat verder alsof er niets is gebeurd.
• Exit 2 — een blokkerende fout. Alleen deze stopt de actie daadwerkelijk.

Als je sys.exit(1) of exit 1 in een shell-hook hebt geschreven in de veronderstelling dat je daarmee blokkeerde, werkt die code in Claude Code als een waarschuwingslog en stopt de actie niet. Wijzig de code in 2. Zie voor meer informatie over hooks en hoe je ze zonder deze valkuil configureert de aparte gids.

Het tweede veelvoorkomende geval is een hook die ongeldige JSON naar stdout schrijft. Claude Code parseert de hookrespons als JSON; staat daar rommel in (een log, voortgangsindicator, emoji), dan wordt de hook als mislukt beschouwd en gaat de actie door. Regel: stdout bevat alleen JSON; al het andere gaat naar stderr.

Het derde geval is een hook die iets leest uit ~/.claude/, dat de veilige modus heeft verborgen. Dit is een normaal scenario; los het niet op door de hook aan te passen, maar controleer aan het begin os.environ.get('CLAUDE_CODE_SAFE_MODE') en beëindig de hook met 0.

Als een MCP-server de schuldige is

Symptomen: MCP-opdrachten zijn beschikbaar, maar retourneren failed zonder duidelijke traceback. Stappen:

1. Voer claude mcp list uit—welke servers zijn gedefinieerd?
2. Schakel servers een voor een uit in ~/.claude.json: wijzig de sleutel claude-server-A in _claude-server-A (zo deactiveer je die zonder hem te verwijderen).
3. Start claude opnieuw. Controleer welke aanroepen werken.
4. Controleer het logboek zodra je de server hebt gevonden: claude mcp logs <name>.
5. Gaat het om een server van derden (@modelcontextprotocol/server-postgres en vergelijkbaar), controleer dan of er recent een nieuwe release is. Het MCP-ecosysteem is nog in beroering; servers gaan regelmatig stuk door updates van Claude Code.

Als je “crasht bij het opstarten, en alleen met twee MCP’s” tegenkomt, vergelijk dan het gedrag in de veilige modus zonder MCP.

Als een skill de schuldige is

Een skill bestaat uit SKILL.md plus code in .claude/skills/<name>/. Symptomen: Claude negeert de skill, past die op het verkeerde moment toe of past die toe maar levert rommel op. Stappen:

1. Open SKILL.md. Controleer de beschrijving—die moet uit 1–2 zinnen bestaan en specifiek beschrijven wanneer je de skill gebruikt. Staat er “een universele helper voor alles”, dan begrijpt Claude niet wanneer die de skill moet aanroepen.
2. Controleer op tegenstrijdigheden met CLAUDE.md. Als CLAUDE.md zegt “schrijf altijd tests”, maar de skillbeschrijving zegt “gebruik voor snelle prototyping zonder tests”, is er sprake van een conflict.
3. Gebruikt de skill externe opdrachten (npm, python, git), controleer dan of die beschikbaar zijn in de systeembrede PATH. Een skill heeft een eigen minimale omgeving.

Wat doe je als de veilige modus niet helpt: diagnose en statusbehoud vóór herstel#

Gebruikersstatus verwijderen is geen diagnosesnelweg. Gebruik onderstaande controles om de fout te identificeren; zijn die onbeslist, bewaar dan het bewijs en onderzoek verder. Elk installatieherstel begint met een gecontroleerde back-up en behoudt bestaand account en de identiteit van het inloggegevensbeheer. Volgorde:

1. claude doctor — automatische diagnostiek. Anthropic schrijft in de documentatie:

2. Controleer op conflicterende installaties. Veel mensen hebben tegelijkertijd zowel een globale npm-versie als de installatie via het native installatieprogramma:

3. Controleer of ANTHROPIC_API_KEY je OAuth-sessie onderschept. Dit is een veelvoorkomende oorzaak van “niets werkt, de sleutel is verlopen”:

Oplossing: voer unset ANTHROPIC_API_KEY uit in de huidige shell-sessie of verwijder de variabele uit ~/.zshrc / ~/.bashrc.

4. Herstel alleen de installatie die de diagnose aanwijst; bewaar eerst alle gebruikersstatus. Falen in veilige modus of een onbeslist doctor-rapport bewijst niet dat gebruikersgegevens weg moeten. Stop alle Claude-sessies en andere schrijvers vóór een consistente back-up. Behoud hetzelfde Unix-account, HOME, OS-inloggegevensbeheer en Anthropic-account; roteer geen sleutels en maak geen vervangende identiteit.

Het volgende back-upvoorbeeld is voor Linux met GNU tar. Gebruik op macOS of Windows een hulpmiddel dat de ACL’s, uitgebreide attributen, koppelingen en metadata van dat platform bewaart en controleer herstel voordat je verdergaat; neem niet aan dat GNU-vlaggen daar werken. Het archief bevat inloggegevens en sessietranscripten: houd het privé en buiten repositories.

# 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"

Alle opdrachten moeten slagen. Het archief dekt de volledige bestaande .claude-boom, inclusief genegeerde/ongevolgde sessies en pluginstatus, en .claude.json, niet alleen Git-instellingen. Is een pad een symlink of staan gegevens op een aparte ingestelde locatie, stop dan en neem het echte doel in dezelfde gecontroleerde back-up op; alleen een koppeling archiveren bewaart het doel niet. Het archief bevat geen macOS Keychain of ander extern inloggegevensbeheer, dus behoud die identiteiten.

Wijst de diagnose specifiek de oude lokale installatie als conflicterende kopie aan, verplaats dan alleen die installatie naar de privéherstelmap in plaats van configuratie en sessies te verwijderen:

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

Verwijder een npm-installatie alleen als de diagnose die als conflict aanwijst en je de native installatie wilt behouden. Gebruik daarna het gedocumenteerde native installatieprogramma zonder .claude of .claude.json te verwijderen:

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

Op Windows blijft de native installatieopdracht:

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

Herstel afzonderlijk. Stop schrijvers opnieuw. Controleer de archiefchecksum en pak uit naar een lege herstelmap zoals hierboven; vergelijk succesvol vóór gebruik. Moet de verplaatste oude installatie terug, bevestig dan eerst dat $HOME/.claude/local niet bestaat en verplaats $backup_dir/legacy-local terug naar precies dat pad. Herstel een gediagnosticeerd instellingenbestand uit de gecontroleerde extractie pas nadat je een huidige vervanger hebt bewaard; leg niet blind de hele boom over bestaande status. Sessies, MCP-instellingen en oorspronkelijke identiteit blijven bewaard. Een Git-snapshot alleen dekt geen genegeerde/ongevolgde transcripten, inloggegevens of bestandssysteemmetadata.

Wat moet je NIET doen wanneer Claude Code kapot is?#

Wijzig geen sleutels vóór de diagnose

“Autorisatie werkt niet” komt in 90% van de gevallen door ANTHROPIC_API_KEY die het abonnement onderschept, een UI-bug in een hook of een defecte MCP. Sleutels roteren lost geen van deze problemen op, maar veroorzaakt wel nog een uur uitval: je moet de oude sleutel intrekken, een nieuwe uitgeven, CI opnieuw ondertekenen met de nieuwe sleutel en de variabelen in productie bijwerken. Voer eerst claude --safe-mode uit. Werkt het? Dan zit het probleem in de aanpassingen; de sleutels hoef je niet aan te raken.

Voer geen volledig herstel uit voordat je de veilige modus hebt geprobeerd

De veilige modus biedt binnen 1 seconde een geïsoleerde omgeving. .claude verwijderen kan sessies, MCP-configuratie en andere ongevolgde status vernietigen. Stel eerst een diagnose, controleer een privéback-up en gebruik alleen voor de werkelijk betrokken installatie- of configuratielaag een omkeerbare verplaatsing.

Raak niet in paniek door een UI-fout in een hook

Controleer voordat je iets aanpast of de hook daadwerkelijk is uitgevoerd (via een log naar stderr of een expliciete uitvoer), in plaats van op de visuele indicator te vertrouwen.

Verhoog de exitcode van een hook niet voordat je de logica hebt gerepareerd

Wanneer je blokkerende hook niet blokkeert, is het verleidelijk om exit 2 in te stellen en het daarbij te laten. Dat is een werkende patch, maar verbergt een ander probleem: als de blokkering een maand niet heeft gewerkt, is alles wat de hook had moeten verbieden toch doorgegaan. Bekijk eerst het git-logboek en zoek precies uit wat er is doorgekomen. Voeg daarna de blokkering toe. Anders maakt een gesloten blokkade niet ongedaan wat er eerder is gebeurd.

Bewerk de productie-CLAUDE.md niet zonder vangnet met de veilige modus

In het beschreven geval bewerk je CLAUDE.md, begint Claude zich vreemd te gedragen en zie je in git diff dat iemand die avond ook een MCP-server en een hook aan de repo heeft toegevoegd. Je geeft je eigen wijziging de schuld, draait die terug en Claude gedraagt zich nog steeds vreemd. Regel: voer vóór git revert claude --safe-mode uit. Blijft het probleem in de veilige modus bestaan, dan had je wijziging er niets mee te maken; terugdraaien is niet nodig.

Geloof niet dat “Claude zijn eigen MCP repareert”

Een typisch scenario: je vraagt Claude om “een bepaalde tool aan de MCP-server toe te voegen”; Claude herschrijft de werkende configuratie, alles gaat stuk en Claude is vervolgens meerdere beurten bezig de schade op te sporen die het zelf heeft veroorzaakt—waarbij het ook de sessiequota opgebruikt. Wanneer MCP kapot is, haal je de configuratie er handmatig bij; laat dat niet aan de agent over. Een deel van diens gereedschapsarsenaal draait ook op MCP, en een kapotte MCP betekent een kapotte diagnosticus.

Waar ga je heen nadat je het hebt gerepareerd?#

Ga na het analyseren van het incident niet meteen weer aan het werk. Voeg eerst preventiemaatregelen toe, zodat het incident zich niet herhaalt. Je kunt uren verliezen aan een second brain (de map business/ met de projectstructuur) en CLAUDE.md; die handmatig herstellen is lastig—dat is een goede reden. Minimale set:

1. ~/.claude/settings.json met permissions.disableBypassPermissionsMode: "disable"—een architectonisch verbod op de bypassmodus, zodat een per ongeluk gestarte --dangerously-skip-permissions simpelweg niet werkt.
2. Hooks voor Read(./env*), Bash(git push --force), Write(./node_modules/**)—zaken die op het niveau van een wet moeten worden onderschept, niet op basis van wensen.
3. Sandboxconfiguratie voor lange autonome runs (/loop, /schedule).
4. /compact met eigen regels voor wat je uit de context wilt verwijderen, zodat Claude zichzelf niet uitput.

Het volledige beschermingsschema met vier lagen staat in de gids “Claude Code zo configureren dat het je project niet ’s nachts kapotmaakt”. De ene gids behandelt preventie voordat je /loop start; de andere het herstel nadat /loop al iets kapot heeft gemaakt. Een logisch paar.

Praktische materialen: Ailoot-documentatie.

Meer materialen en tools: Ailoot.