Cursor checkpoints: what Restore Checkpoint undoes, what it misses, what to use instead

The short answer

Cursor checkpoints are local snapshots of your code that the Agent takes automatically before significant changes, capturing the state of the files it modifies. Restore Checkpoint reverts those files to an earlier point in the chat; it doesn’t remove messages from the conversation.¹ Cursor’s docs say to use checkpoints only for undoing Agent changes and to use Git for permanent version control.¹

What checkpoints can’t do is undo anything that wasn’t a file edit in your project: a command the Agent ran in the terminal, a row it deleted in a database, a deploy it triggered. Cursor staff have said its file-protection settings only cover deletes done through Cursor’s own tools, and terminal commands can bypass them.² Keep Git, and keep backups for everything outside the repo.

What a checkpoint saves

From Cursor’s documentation:¹

• Checkpoints save snapshots of your codebase during an Agent session.
• The Agent creates them automatically before significant changes, capturing the state of all modified files.
• You can click a checkpoint in the chat timeline to preview your files at that point, then restore. You can also use the Restore Checkpoint button on an earlier request, or the + button when hovering over a message.
• Restoring reverts files only. The conversation stays.
• Checkpoints are stored locally and separately from Git.

That design suits the way most people use Cursor’s Agent: try an approach, look at the diff, and roll back if it went the wrong way. It’s fast because it doesn’t touch Git, and it’s per chat, so it doesn’t pollute your commit history.

It’s also why checkpoints aren’t a backup. They live on one machine, outside version control, tied to a chat.

What restore can’t reach

A checkpoint is a set of file snapshots. Anything the Agent changed that isn’t one of those files is out of its reach by design:

The Cursor staff reply we cite was about File-Deletion Protection and External-File Protection. Those settings protect against deletes through Cursor’s built-in tools; terminal commands run directly in the shell, so they can bypass them. The staff member’s suggestion was to turn off auto-run so the Agent asks before every terminal command.² That’s the honest answer: the protection for shell commands is a person reading them before they run.

This is the same gap we found for other agents’ undo features. Our post on undo for agent sessions compares them, and Cursor agent deleted my files walks through recovery after a shell delete.

When the restore button goes missing

Checkpoints are only useful if you can reach them, and users have reported times when they couldn’t. These are user reports in Cursor’s own forum, not a measure of how often it happens:

• August 2026, Cursor 3.12.30 on Windows. A user reported the Restore Checkpoint control missing in local Agent chats, while checkpoint folders still existed on disk. Cursor staff said the issue was being tracked; asked on 3 September 2026, staff said it was not yet resolved.³ Staff suggested scrolling up so older turns load, or sending a new message, to bring the control back, and pointed to Local History: Find Entry to Restore as a recovery path that works independently of checkpoints.³
• August 2025, Cursor 1.4.5. A user reported that after restoring a checkpoint, they couldn’t undo the restore, although the dialog said they could. Staff said they would investigate.⁴

Software has bugs; that’s not the point. The point is that your only copy of working code shouldn’t depend on one button in a chat pane.

Recovery paths, in order

If the Agent broke something, try these from fastest to slowest:

1. Restore Checkpoint in the chat, for files the Agent edited in this session.¹
2. Git: git diff to see what changed, git restore <file> for uncommitted damage to tracked files, git reflog if commits were rewritten. Files never committed are much harder to recover.
3. Local History. Cursor is built on VS Code³, which keeps local history: an entry with the file’s contents each time you save, shown in the Timeline view. By default it’s on, keeps up to 50 entries per file and skips files over 256 KB.⁵ It only has versions that were saved, so it helps with edits more than with deletes of files you never opened.
4. Your OS (Time Machine, File History) or your editor’s trash, for deleted files.
5. Backups and point-in-time restore for anything outside the repo: databases, buckets, cloud resources. If the Agent ran a destructive database command, go here first and fast; see our restore one Postgres table guide.

Set up before you need it

1. Commit before every Agent task. A clean working tree makes git diff and git restore precise. Checkpoints are for the minutes inside a task; commits are for everything else.¹
2. Turn off auto-run for terminal commands, or keep its allowlist short, so destructive commands wait for you.²
3. Don’t give the Agent production credentials. A checkpoint can’t undo a database write, so the best protection is not being able to make one. Our checklist before an agent touches production covers the rest.
4. Check local history settings. If you work with large generated files, the 256 KB default limit means they won’t be kept.⁵
5. Push often. A remote copy survives a local delete that takes the .git folder with it.

Questions people ask

Do Cursor checkpoints replace Git?

No. Cursor’s docs say checkpoints are for undoing Agent changes and Git is for permanent version control.¹

Does Restore Checkpoint undo terminal commands?

Don’t rely on it. Checkpoints snapshot files the Agent modifies¹, and Cursor staff say terminal commands can bypass its file-protection settings.² Effects outside your files, such as database writes, can’t be reverted by a file snapshot.

Where are Cursor checkpoints stored?

Locally, separately from Git.¹ One Windows user found them under Cursor’s global storage folder in AppData.³

To try a gate that stops destructive commands and database writes before they run, open the playground in your browser. To grade what Cursor and your other agents can reach on your own machine, run npx deedglass scan (the grade, explained).

Written with AI assistance and checked against our claims register.