In Cursor, what does restoring an Agent checkpoint revert, what does it leave alone, and why is it no substitute for Git?
answer
- made automatically before big edits
- Restore Checkpoint on an earlier message
- files only; the messages stay
- stored locally, apart from Git
- fork the chat to trim history
basics
~20 sRestoring a Cursor checkpoint reverts the files back to that point while every chat message stays. Checkpoints are local snapshots kept apart from Git, meant only for undoing Agent's changes; Git remains the permanent, shareable history.
solid answer
~50 sAgent creates checkpoints automatically before significant changes, capturing the state of the files it modified. You restore one by clicking it in the chat timeline (which previews the files first), with the `Restore Checkpoint` button on an earlier request, or with the + button when hovering a message. Restoring reverts the files to that state but does **not** remove messages from the conversation; to shorten the conversation, fork the chat from an earlier message. Checkpoints are stored locally and separately from Git, so they are not commits, are not pushed and are not shared through Git, and Cursor's docs say to use them only for undoing Agent's changes and Git for permanent version control. Because a restore works on files, effects outside the files stay as they were: a migrated database, a published package, a pushed branch.
go deeper
Know where Restore Checkpoint is, that Agent creates checkpoints by itself, and that restoring reverts files while the chat keeps its messages.
Explain why checkpoints are not version control: local, separate from Git, unshared, and blind to anything outside the files.
Decide how a team protects itself before long Agent runs: commit first, know which commands have effects a checkpoint cannot undo, and fork the chat after a bad turn.
Set the expectation that checkpoints are a personal undo, and that Git and reviewed history stay the team's system of record for agent-written code.
## What a checkpoint is A **checkpoint** is a snapshot of your codebase that Cursor's **Agent** takes during a session. Agent creates them **automatically before making significant changes**, capturing the state of every file it has modified. You do not create them yourself and you do not name them. They exist so that, when Agent takes a wrong turn, you can put the files back the way they were before it did. Two properties define them: - They are **stored locally**, on your machine. - They are **separate from Git**: a checkpoint is not a commit, not a stash and not a branch. ## Restoring one There are three ways to get back to a checkpoint: 1. Click a checkpoint in the **chat timeline** to preview your files at that point, then restore. 2. Click **`Restore Checkpoint`** on an earlier request; the help pages place it at the bottom right when you hover over a previous message. 3. Use the **+** button that appears when hovering over a message. Restoring reverts **all** the files to the state captured at that point, which rolls back everything Agent changed after it. ## What a restore changes and what it leaves | Thing | After a restore | |---|---| | Files Agent modified after that point | Reverted to the snapshot | | The conversation | Unchanged; every message stays | | Git history (commits, branches, the remote) | Untouched; checkpoints are separate from Git | | Effects outside the files: a database a migration changed, a package that was published, a branch that was pushed | Untouched; a restore only reverts files | The conversation point surprises people. Restoring does **not** delete the later messages, so the agent still sees its own wrong turn in the history. To shorten the conversation itself, **fork the chat** from an earlier message, or start a new chat. The last row matters for any run that executed commands. A checkpoint can put a migration file back, but the database it already ran against keeps the change. Undoing that is your job. ## Checkpoints versus Git Cursor's own guidance is blunt: use checkpoints **only for undoing Agent changes**, and use **Git for permanent version control**. | | Checkpoint | Git commit | |---|---|---| | Created by | Agent, automatically | You, deliberately | | Lives | Locally, outside the repository history | In the repository, and on the remote once pushed | | Shared with the team | No | Yes, once pushed | | Purpose | Rolling back an Agent detour | The project's lasting history | The reasons it cannot stand in for Git follow from that table: - A checkpoint exists only on the machine that made it, so it does not survive moving to another machine or to a teammate. - It has no message, no author and no review, so it explains nothing later. - It covers Agent's work in a session, not the project's history. ## A worked example Suppose you ask Agent to rename a configuration option across a service. It edits five files, runs the test suite, sees failures and starts rewriting tests to match its mistake. You notice three messages later. 1. Click the checkpoint in the chat timeline from before the rename and preview the files. 2. Restore. The five files return to their earlier state. 3. The chat still contains the whole detour. Fork the chat from the message before the rename, or tell Agent explicitly what went wrong and what to keep. 4. Rerun the request with the constraint it missed, for example that test files must not change. Here the only lasting changes were file edits, so the restore was enough. Had a command written to a shared database or pushed a branch, that part would have needed undoing by hand. ## Using checkpoints well - **Commit before a long Agent run.** A clean commit gives you a known-good state that is independent of any one session. - **Restore early.** When Agent has clearly misread the task, restoring and re-prompting is cheaper than asking it to undo its own changes. - **Pair restore with a cleaner prompt.** Since the messages remain, say what was wrong, or fork the chat so the bad attempt is out of the history. - **Plan mode uses the same idea.** When a build from a plan goes wrong, Cursor suggests reverting the files (the **Revert** button on an earlier message, then **Confirm**), refining the plan and building again. - **Watch for side effects.** Before letting Agent run commands that change things outside the repository, decide how you would undo them, because a checkpoint will not.
- After restoring a Cursor checkpoint, the next answer still builds on the agent's wrong turn. Why, and how do you remove it?Restoring reverts files only; the messages stay in the conversation, so the agent still reads its own earlier attempt. Fork the chat from a message before the wrong turn, or start a new chat with a corrected request. Cursor also recommends a new chat when you switch tasks.
- Can a teammate pick up your Cursor checkpoints to see what Agent tried before you restored?Not through Git. Checkpoints are stored locally on your machine and kept separate from Git, so they are not commits and nothing pushes them. Anything a teammate needs to see has to be committed and pushed, or shared another way.
- Restoring a checkpoint also deletes the later messages from the chat
- Cursor checkpoints are Git commits on a hidden branch
- With checkpoints you no longer need to commit during long Agent runs
- Restoring a checkpoint rolls back a database migration the agent ran
- You have to create a checkpoint by hand before each prompt