File Checkpointing in Claude Agent SDK Workflows

## Overview

File checkpointing tracks file modifications made through the Write, Edit, and
NotebookEdit tools during an Agent SDK session, so you can rewind files to a
previous state. It is useful for undoing unwanted changes, exploring
alternatives, and recovering from errors before a risky refactor.

## Enable checkpointing

Set `enableFileCheckpointing` (TS) / `enable_file_checkpointing` (Python), and add
the `replay-user-messages` extra arg so each user message in the stream carries a
checkpoint UUID:

```typescript
const opts = {
  enableFileCheckpointing: true,
  permissionMode: "acceptEdits" as const,
  extraArgs: { "replay-user-messages": null },
};
```

## Capture the checkpoint and session id

Each user message in the response stream has a `uuid` that serves as a checkpoint;
capture the first one to restore all files to their original state. Capture
`session_id` too if you want to rewind after the stream completes.

```typescript
for await (const message of response) {
  if (message.type === "user" && message.uuid && !checkpointId) checkpointId = message.uuid;
  if ("session_id" in message && !sessionId) sessionId = message.session_id;
}
```

## Rewind files

After the stream completes, resume the session with an empty prompt and call
`rewindFiles()` (TS) / `rewind_files()` (Python):

```typescript
const rewindQuery = query({ prompt: "", options: { ...opts, resume: sessionId } });
for await (const msg of rewindQuery) {
  await rewindQuery.rewindFiles(checkpointId);
  break;
}
```

You can also rewind during the stream (keep the latest UUID and rewind on a revert
condition), or from the CLI:
`claude -p --resume <session-id> --rewind-files <checkpoint-uuid>`.

## Multiple restore points

Store each user-message UUID in an array to rewind to an intermediate state (for
example, keep a refactor but undo later test changes).

## Limitations

- Write/Edit/NotebookEdit tools only; Bash-driven changes are not tracked.
- Checkpoints are tied to their session.
- File content only; directory create/move/delete is not undone.
- Local files only.

## Troubleshooting

- No UUIDs on user messages: add the `replay-user-messages` extra arg.
- "ProcessTransport is not ready for writing": rewinding after the loop finished;
  resume with an empty prompt, then call rewind on the new query.

## Source

- Rewind file changes with checkpointing: https://code.claude.com/docs/en/agent-sdk/file-checkpointing