Rewind file changes with checkpointing changedagent-sdk/file-checkpointing
Nearest release: v2.1.309, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Oct 2026 22:51 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+11added
Lines−11removed
From line
2
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 2, old and new numbered
/
from line 2
22
33> Track file changes during agent sessions and restore files to any previous state
44
5File checkpointing tracks file modifications made through the [Write](/docs/en/tools-reference.md#write-tool-behavior), [Edit](/docs/en/tools-reference.md#edit-tool-behavior), and [NotebookEdit](/docs/en/tools-reference.md#notebookedit-tool-behavior) tools during an agent session, allowing you to rewind files to any previous state. To watch a rewind restore a file, jump to the [interactive example](#try-it-out).
5File checkpointing tracks file modifications made through the [Write](https://code.claude.com/docs/en/tools-reference.md#write-tool-behavior), [Edit](https://code.claude.com/docs/en/tools-reference.md#edit-tool-behavior), and [NotebookEdit](https://code.claude.com/docs/en/tools-reference.md#notebookedit-tool-behavior) tools during an agent session, allowing you to rewind files to any previous state. To watch a rewind restore a file, jump to the [interactive example](#try-it-out).
66
77> [!WARNING]
88>
9> `rewindFiles()` doesn't undo what `sed -i` or another Bash command did to a file, unless a tool such as Write or Edit had modified that file in the main conversation. [Subagent](/docs/en/agent-sdk/subagents.md) edits aren't tracked, while edits from a [skill with `context: fork`](/docs/en/skills#run-skills-in-a-subagent) running in the foreground are.
9> `rewindFiles()` doesn't undo what `sed -i` or another Bash command did to a file, unless a tool such as Write or Edit had modified that file in the main conversation. [Subagent](https://code.claude.com/docs/en/agent-sdk/subagents.md) edits aren't tracked, while edits from a [skill with `context: fork`](https://code.claude.com/docs/en/skills#run-skills-in-a-subagent) running in the foreground are.
1010
1111## How checkpointing works
1212
from line 16
1616>
1717> File rewinding restores files on disk to a previous state. It does not rewind the conversation itself. The conversation history and context remain intact after calling `rewindFiles()` (TypeScript) or `rewind_files()` (Python).
1818
19When you rewind to a checkpoint, Claude Code deletes the files it created and restores the files it modified to their content at that point. Claude Code skips a tracked path that is a symlink, hard link, or other non-regular file. It also skips a tracked file whose parent directory no longer resolves to its checkpoint-time location, or whose backup it can't read safely. [`RewindFilesResult`](/docs/en/agent-sdk/typescript#rewindfilesresult) counts every skipped path in its `skippedLinks` field. Skipping requires Claude Code v2.1.216 or later; before v2.1.216, a rewind wrote and deleted through links at tracked paths.
19When you rewind to a checkpoint, Claude Code deletes the files it created and restores the files it modified to their content at that point. Claude Code skips a tracked path that is a symlink, hard link, or other non-regular file. It also skips a tracked file whose parent directory no longer resolves to its checkpoint-time location, or whose backup it can't read safely. [`RewindFilesResult`](https://code.claude.com/docs/en/agent-sdk/typescript#rewindfilesresult) counts every skipped path in its `skippedLinks` field. Skipping requires Claude Code v2.1.216 or later; before v2.1.216, a rewind wrote and deleted through links at tracked paths.
2020
2121## Implement checkpointing
2222
from line 139
139139| Enable checkpointing | `enable_file_checkpointing=True` | `enableFileCheckpointing: true` | Tracks file changes for rewinding |
140140| Receive checkpoint UUIDs | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | Required to get user message UUIDs in the stream |
141141
142The lead example under [Implement checkpointing](#implement-checkpointing) also sets the permission mode to `acceptEdits`, which approves the agent's file edits without a prompt. For more information, see [Permission modes](/docs/en/agent-sdk/permissions.md#permission-modes).
142The lead example under [Implement checkpointing](#implement-checkpointing) also sets the permission mode to `acceptEdits`, which approves the agent's file edits without a prompt. For more information, see [Permission modes](https://code.claude.com/docs/en/agent-sdk/permissions.md#permission-modes).
143143
144144**2. Capture checkpoint UUID and session ID**
145145
from line 153
153153
154154To rewind after the stream completes, resume the session with an empty prompt and call `rewind_files()` (Python) or `rewindFiles()` (TypeScript) with your checkpoint UUID. Enable checkpointing on the resumed session's options too, and call rewind from inside the response loop. You can also rewind during the stream. See [Checkpoint before risky operations](#checkpoint-before-risky-operations) for that pattern.
155155
156If you capture the session ID and checkpoint ID, you can also rewind from the CLI. This command requires the `claude` executable, which comes from [installing Claude Code](/docs/en/setup.md). The SDK enables checkpointing for you, but when you run `claude -p` directly you must set the `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` environment variable:
156If you capture the session ID and checkpoint ID, you can also rewind from the CLI. This command requires the `claude` executable, which comes from [installing Claude Code](https://code.claude.com/docs/en/setup.md). The SDK enables checkpointing for you, but when you run `claude -p` directly you must set the `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` environment variable:
157157
158158```bash theme={null}
159159CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>
from line 376
376376
377377This complete example creates a small utility file, has the agent add documentation comments, shows you the changes, then asks if you want to rewind.
378378
379Before you begin, make sure you have the [Claude Agent SDK installed](/docs/en/agent-sdk/quickstart.md).
379Before you begin, make sure you have the [Claude Agent SDK installed](https://code.claude.com/docs/en/agent-sdk/quickstart.md).
380380
381381**1. Create a test file**
382382
from line 602
602602| Limitation | Description |
603603| - | - |
604604| Bash command changes | Rewinding doesn't undo changes a Bash command made, except in files the main conversation had already edited with a tool such as Write or Edit |
605| Subagent edits | Edits a [subagent](/docs/en/agent-sdk/subagents.md) applies aren't tracked, except a skill with `context: fork` running in the foreground. A rewind reverts them only in files the main conversation had already edited; use git to revert the rest |
605| Subagent edits | Edits a [subagent](https://code.claude.com/docs/en/agent-sdk/subagents.md) applies aren't tracked, except a skill with `context: fork` running in the foreground. A rewind reverts them only in files the main conversation had already edited; use git to revert the rest |
606606| Same session | Checkpoints are tied to the session that created them |
607607| File content only | Creating, moving, or deleting directories is not undone by rewinding |
608608| Local files | Remote or network files are not tracked |
from line 657
657657
658658## Next steps
659659
660* **[Sessions](/docs/en/agent-sdk/sessions.md)**: learn how to resume sessions, which is required for rewinding after the stream completes. Covers session IDs, resuming conversations, and session forking.
661* **[Permissions](/docs/en/agent-sdk/permissions.md)**: configure which tools Claude can use and how file modifications are approved. Useful if you want more control over when edits happen.
662* **[TypeScript SDK reference](/docs/en/agent-sdk/typescript.md)**: complete API reference including all options for `query()` and the `rewindFiles()` method.
663* **[Python SDK reference](/docs/en/agent-sdk/python.md)**: complete API reference including all options for `ClaudeAgentOptions` and the `rewind_files()` method.
660* **[Sessions](https://code.claude.com/docs/en/agent-sdk/sessions.md)**: learn how to resume sessions, which is required for rewinding after the stream completes. Covers session IDs, resuming conversations, and session forking.
661* **[Permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)**: configure which tools Claude can use and how file modifications are approved. Useful if you want more control over when edits happen.
662* **[TypeScript SDK reference](https://code.claude.com/docs/en/agent-sdk/typescript.md)**: complete API reference including all options for `query()` and the `rewindFiles()` method.
663* **[Python SDK reference](https://code.claude.com/docs/en/agent-sdk/python.md)**: complete API reference including all options for `ClaudeAgentOptions` and the `rewind_files()` method.
664664
No line in this hunk matches that.