Na twintig minuten refactoren neemt de agent een verkeerde afslag: drie bestanden opnieuw ingedeeld rond een abstractie die ik niet wil. Voordat checkpoints bestonden, kostte dat me een git checkout waar ik even goed over moest nadenken, of een stash, of een handvol reverts die ik met de hand zat te typen.
Nu kost het twee keer Escape.
Checkpointing is een van de betere dingen die Anthropic aan Claude Code heeft toegevoegd. Het haalde een echte drempel weg om dingen uit te proberen, zonder dat ik mijn manier van werken hoefde aan te passen. Het product zelf verkoopt het als "Undo anything", met de terechte toevoeging dat je git-historie schoon blijft.
Het loont om precies te weten wat daar wel en niet onder valt, want je hebt er veel meer aan zodra je ziet hoe het in elkaar zit. De grenzen staan gedocumenteerd, ze zijn logisch, en ze volgen één regel die je makkelijk onthoudt.
Wat een checkpoint precies is
Claude Code legt de staat van je code vast vóór elke prompt die je stuurt. Een niveau dieper maakt hij een backup van losse bestanden voordat hij ze aanpast met zijn edit-tools: Write, Edit en NotebookEdit. Je prompts zijn dus je herstelpunten.
Een paar getallen om te onthouden:
- 100 checkpoints per sessie. Valt er een oude af, dan verdwijnen de snapshots waar geen enkel resterend checkpoint meer naar verwijst. Met één uitzondering: de eerste snapshot van elk bestand blijft staan, want de VS Code-extensie gebruikt die als basis voor de diffs van je sessie.
- Checkpoints worden bij het gesprek bewaard, dus
/rewindwerkt nog steeds als je de sessie dagen later hervat. - Ze verdwijnen samen met de sessie na 30 dagen, wat je aanpast met
cleanupPeriodDays.
Je kunt het geheel ook uitzetten: in je settings heet die schakelaar "Rewind code (checkpoints)". In cloud-sessies werkt het nog niet.
Esc Esc, en de zes keuzes
Typ /rewind, of druk twee keer op Esc terwijl het invoerveld leeg is. Dat laatste detail verrast mensen: staat er tekst in het veld, dan wist dubbel Esc die tekst in plaats van het menu te openen. Die tekst gaat wel naar je invoerhistorie, dus met Up heb je hem zo weer terug.
Het menu toont elke prompt die je deze sessie hebt gestuurd. Kies er een, en kies dan een actie:
| Actie | Wat het doet |
|---|---|
| Restore code and conversation | Allebei terug naar dat punt |
| Restore conversation | Draait de berichten terug, je bestanden blijven zoals ze zijn |
| Restore code | Draait de bestandswijzigingen terug, het gesprek blijft compleet |
| Summarize from here | Vat het gesprek vanaf dat punt samen |
| Summarize up to here | Vat alles ervóór samen, latere berichten blijven intact |
| Never mind | Terug naar de lijst, er verandert niets |
De twee code-opties verschijnen alleen als het gekozen checkpoint ook echt bijgehouden wijzigingen heeft om terug te draaien. Een menu dat een knop weglaat als die toch niets zou doen is een kleinigheid, maar precies daarin zit het verschil tussen een tool die je vertrouwt en een tool die je elke keer eerst even test.
Draai je het gesprek terug, dan zet hij je oorspronkelijke prompt weer in het invoerveld, klaar om aan te passen en opnieuw te sturen. Daar is de functie voor gebouwd: terug naar vlak vóór de verkeerde afslag, het beter formuleren, opnieuw beginnen.
De twee samenvat-opties zijn in feite een /compact die je op een specifiek stuk van de sessie richt. Aan je bestanden verandert niets, en de oorspronkelijke berichten blijven in het transcript staan, dus je raakt niets kwijt. Selecteer de optie en typ in de regel add context (optional) om te sturen wat de samenvatting moet bewaren.
Wil je de oorspronkelijke sessie intact houden en er een tweede aanpak naast proberen, dan gebruik je /branch of claude --continue --fork-session. Dit hoort allemaal bij je context-budget, en samenvatten is daarvan het meest precieze instrument.
Nog een mooie: heb je eerder in hetzelfde proces /clear gebruikt, dan staat bovenaan de rewind-lijst een extra regel, /resume <session-id> (previous session). Vanaf 2.1.191 kun je dus terugstappen tot voorbij een clear waar je spijt van hebt.
Wat hij bijhoudt, en wat bij git blijft
Dit is de regel waar de hele functie op draait: checkpointing dekt de wijzigingen die de hoofdagent maakt met zijn eigen edit-tools. De rest blijft het werk van git.
| Wel gedekt | Niet gedekt |
|---|---|
Wijzigingen via Write, Edit, NotebookEdit | Alles wat een bash-commando aanpaste (rm, mv, cp, sed -i) |
| Bestanden die tijdens de sessie ontstaan | Mappen die worden aangemaakt, verplaatst of verwijderd |
| Bestanden die tijdens de sessie wijzigen | Edits uit andere sessies die tegelijk lopen, en je eigen handwerk |
| Lokale bestanden | Bestanden op een netwerkschijf of op afstand |
Die verdeling valt goed te verdedigen. De tool kan zijn eigen edit-pad snel en exact vastleggen. Hij weet niet wat npm install, een formatter of een migratie in je working tree heeft uitgespookt, en hij doet ook niet alsof.
In de praktijk betekent het: hoe meer van een taak via bash loopt, hoe meer ervan bij een commit hoort in plaats van bij een checkpoint. Een sessie met zorgvuldige bestandsedits is volledig gedekt. Bij een sessie die een codemod draait, een schemadump opnieuw genereert en een lockfile herschrijft geldt dat grotendeels niet.
Twee dingen die uit die regel volgen en makkelijk over het hoofd worden gezien. Een restore verwijdert de bestanden die de agent sinds dat punt heeft aangemaakt, je krijgt dus echt de oude staat terug. En checkpoints horen bij de sessie waarin ze gemaakt zijn.
De subagent-regel die je uit je hoofd wilt kennen
Deze zou ik op een post-it schrijven, want het is het minst intuïtieve deel, en tegelijk het deel waarvan je precies kunt weten hoe het zit.
Een subagent past bestanden aan met dezelfde tools als de hoofdagent, maar die edits belanden meestal buiten de checkpoints van jouw sessie. Of een rewind ze terughaalt hangt volledig af van hoe die subagent draaide:
- Een skill met
context: forkdie op de voorgrond draait werkt tijdens jouw eigen beurt in je working tree, dus een rewind herstelt die edits gewoon. - Elke andere subagent wordt niet hersteld. Dat geldt ook voor een forked skill die op de achtergrond draait, wat de standaard is, en voor een
/code-review --fixop de achtergrond. Daarvoor val je terug op git.
Dezelfde skill valt er dus wel of niet onder, afhankelijk van één flag in de frontmatter. Verdeel je werk over parallelle agents in worktrees, dan is je vangnet daar de branch, precies zoals vóór checkpointing.
Wanneer een restore een bestand overslaat
Sinds 2.1.216 weigert een restore te schrijven naar een bijgehouden pad dat inmiddels een symlink, een hard link of een ander niet-regulier bestand is. Hij slaat ook bestanden over waarvan de bovenliggende map niet meer op dezelfde plek uitkomt als tijdens het checkpoint, of waarvan hij de backup niet veilig kan lezen. Je krijgt dan de waarschuwing Restored the code, but skipped N files, en die bestanden houden hun huidige inhoud.
Twee doodgewone situaties vallen hieronder: configbestanden die een dotfile-manager je project in symlinkt, en alles wat pnpm met hard links op zijn plek zet.
Dit is een echte verbetering. Vóór 2.1.216 schreef en verwijderde een rewind dwars door die links heen, zonder melding, en dat is een stuk vervelender dan een waarschuwing. Wil je zien welke paden precies zijn overgeslagen, zet dan /debug aan vóór je herstelt en lees ~/.claude/debug/<session-id>.txt.
Terugdraaien vanuit een script
Dezelfde machinerie is ook buiten je interactieve sessie beschikbaar. In de Agent SDK zet je enableFileCheckpointing: true (of enable_file_checkpointing=True), voeg je replay-user-messages toe zodat user-berichten met een UUID binnenkomen, bewaar je de UUID die je wilt, en roep je rewindFiles() of rewind_files() aan. Let op: dit herstelt alleen bestanden, het gesprek blijft staan waar het staat.
Vanaf de CLI ziet dat er zo uit:
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>De flag staat op zichzelf, hij heeft --resume nodig, hij weigert samen met een prompt te draaien, en hij staat niet in claude --help. Zonder de environment-variabele krijg je "File rewinding is not enabled", de foutmelding waar ik anders een uur op had zitten staren als de documentatie het niet had vermeld.
Daarmee heb je een prima patroon voor onbeheerde runs: bewaar de UUID van de laatste beurt waarvan je weet dat hij goed was, en draai de bestanden automatisch terug zodra je eigen validatie faalt.
Hoe ik het gebruik
Rewind is mijn standaardreactie op een verkeerde richting, en het heeft veranderd hoe makkelijk ik een agent dingen laat proberen. Twee tikken, terug naar vlak vóór de afslag, een betere prompt sturen. Geen branch, geen stash, geen reverts om door te lezen.
Daaromheen doet één gewoonte het meeste werk: committen voordat ik iets van omvang uit handen geef. Binnen zijn grenzen is rewind betrouwbaar, en de commit dekt de andere helft af. Bash-wijzigingen, output van subagents, die map die hij verplaatste, de sessie die je afgelopen donderdag hebt afgesloten.
De documentatie zegt het onomwonden, en zo houd ik het ook het liefst uit elkaar: checkpoints zijn er voor snel herstel binnen een sessie, versiebeheer is er voor blijvende historie. Dat zijn twee verschillende taken, en de tool claimt er maar één van.
Goed om in je achterhoofd te houden: een rewind zet je bestanden terug, maar buiten je machine is gebeurd wat er gebeurd is. De migratie draaide, de commit ging de deur uit, de webhook vuurde. Zodra er iets buiten je working tree is beland ben je niet meer aan het terugdraaien, dan ben je een incident aan het afhandelen, en verandert de bestandshistorie van redmiddel in bewijsmateriaal.
Binnen je working tree is dit de goedkoopste manier van terugdraaien die de tool ooit heeft gehad. Leer waar het ophoudt en je hoeft er verder niet meer over na te denken.