Cursor restore checkpoint: how it works and when it fails
To use Cursor restore checkpoint, click any checkpoint in the chat timeline to preview your files at that point, then restore to revert all files to that state. Restoring reverts files only and leaves the conversation as it is. Replies on the Cursor forum say it undoes only edits made with the agent's file-editing tools, not terminal commands. Checkpoints are local and separate from Git, so commit before an agent session.
Something in an Agent run went wrong and you want your files back. This page shows the steps, what a checkpoint covers and where it falls short.
01How to use Cursor restore checkpoint
These are the steps:
- Find the point in the chat timeline that comes before the change you want to take back.
- Click that checkpoint. Cursor previews your files at that point.
- Choose to restore. Cursor reverts all files to that state.
Restoring a checkpoint reverts files only; it does not remove messages from the conversation. So the chat stays as it was, and you can keep talking to the agent from the restored files.
02Save your current state before you restore
Warning: restoring reverts all files to the chosen state. Anything you did after that point, including edits you wanted to keep, can go with it. Cursor shows a preview of your files at that point before you restore, so look at it first.
Then protect what you want to keep. A commit lives in Git, and a checkpoint does not, because Cursor stores checkpoints locally and separate from Git. If the current files hold work you want, commit it before you restore, so the restore cannot take it. Before you use Cursor restore checkpoint on a project with edits you made by hand, this is the one step worth doing. Your own edits are also the kind that, according to replies on the Cursor forum, a restore leaves in place.
If you are not ready to commit, stash your work instead. Warning: git stash -u takes your uncommitted changes out of the project folder, including untracked files (new files Git has never tracked); it saves them in the stash and then cleans them from the folder:
git stash -uAfter the restore, git stash pop applies the saved state on top of your files and removes it from the stash list. If the restore changed the same lines, applying can fail with conflicts, which is why a commit is the simpler choice:
git stash pop03After you restore
Check three things. Open the files you care about and read them, because the restore reverted all files to the chosen state. Look at the chat: it still shows every message, since restoring does not remove messages from the conversation. Then ask the agent to continue from the restored files, and say plainly which change you want to avoid this time. If something still looks wrong, the cause may be a change that a checkpoint never tracked, such as one made by a terminal command or a subagent. In that case go to the Git section below.
04What a Cursor checkpoint is
A checkpoint is a snapshot of your codebase taken during an Agent session. Agent is the part of Cursor that makes changes for you. It creates checkpoints automatically before making significant changes, capturing the state of all modified files.
Checkpoints are stored locally and separate from Git. Use them only for undoing Agent changes, and Git for permanent version control. Treat a checkpoint as a short-term undo, not a backup.
05What a restore brings back and what it leaves
A restore covers less than the word suggests. This is what to expect from it.
| What changed | Does a restore bring it back? (forum replies for the last four rows) |
|---|---|
| Files the agent edited after that checkpoint | Yes, a checkpoint captures the state of all modified files, and a restore reverts all files to that state |
| The conversation | No, restoring reverts files only and leaves the messages |
| Changes made by terminal commands, like a Python or sed script | No, they stay in place |
| Edits made by subagents | No, they stay in place |
| Edits you made yourself | No, they stay in place |
| Jupyter notebooks (.ipynb files) | No, they are not restored |
If a terminal command or a subagent changed your files, plan for Git, not the checkpoint.
06When a restore does not bring files back
In a forum thread about file deletion, the reporter wrote that the deletion "cannot be recovered from checkpoint". That is one user's account, not a measured failure rate. Stories of Cursor deleting files, and what to do afterwards, are on Cursor deleted files, and the run mode that lets the agent act without asking is on Cursor YOLO mode.
07Before the next agent session
Committing before an agent session is the most reliable way to roll back, as a reply on the Cursor forum puts it. This works because a commit lives in Git, where a checkpoint does not.
Two Git words help here. The working tree is the files in your project folder as you see them. The index, or staging area, is the list of changes you have added for the next commit.
Use this when one tracked file is gone and you want it back from the index. Warning: it rewrites that file in your working tree, so unstaged edits in it are replaced:
git restore <file>Replace <file> with the real path. Git may also remove a tracked file that does not exist in the source you restore from, so name only the files you want. Other cases have their own pages: restore a deleted file, undo a Git reset and restore untracked files.
08Other tools have the same idea
Claude Code has a similar undo with its own limits: its checkpoints track Claude's file edits and not files that only Bash commands changed. Read Claude Code undo or Claude Code checkpoints if you use both. A Mac backup is another layer outside any editor; see restore from Time Machine.
09Cursor restore checkpoint: what to remember
Click the checkpoint in the chat timeline and restore. Expect files only, not the conversation. Expect gaps: replies on the Cursor forum say changes from terminal commands, subagents, manual edits and notebooks stay as they are. Commit before the session, and again before a restore if the current files matter.
A checkpoint helps after an edit. Artificial Immunity's free, open-source core watches the agents on your Mac, including Cursor, and every program start, and reports what it finds, without stopping anything.
FAQ
How do I restore changes in Cursor?
Click any checkpoint in the chat timeline to preview your files at that point, then restore to revert all files to that state. If the checkpoint does not bring the files back, use Git.
How do I restore my Cursor back to normal?
Restore the checkpoint from before the bad change. Restoring reverts files only; it does not remove messages from the conversation.
What is a Cursor checkpoint?
A snapshot of your codebase during an Agent session. Agent creates checkpoints automatically before making significant changes.
Is a Cursor checkpoint the same as a Git commit?
No. Cursor's docs say checkpoints are stored locally and separate from Git, and to use Git for permanent version control.
Why did Restore Checkpoint not undo my changes?
A Cursor forum reply says Restore Checkpoint only undoes edits the agent made with its file-editing tools. Changes made by terminal commands or subagents, and edits you made yourself, stay in place. That is a forum reply, not documentation.
Can a checkpoint bring back files the agent deleted?
One forum reporter wrote that a deletion could not be recovered from a checkpoint. That is one user's report, not a measured rate. Check Git and your Mac's backups too.