The Safeguard CLI snapshots every file its assistant writes or edits, before each change. To undo, find the session with safeguard sessions list, list its checkpoints, preview a restore with --dry-run, then restore. In the interactive terminal, /rewind uses the same checkpoints. Files written by shell commands are not snapshotted, so keep git as well.
Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. You can also connect Claude or ChatGPT to the Safeguard MCP server and use your Safeguard data from the chat you already use.
Letting an assistant edit code is easier when you know you can take it back. This guide shows exactly what the CLI keeps, how to get files back from the command line and from inside a session, how to undo a restore you regret, and where git still has to do the work. Every command here comes from the CLI's own --help output on version 11.11.0, which the Safeguard CLI docs say is the reference when the two disagree.
What you will have at the end
After this guide you will be able to:
- Start a session with a name or id you choose, so finding it later takes one command.
- List every checkpoint a session took, oldest first.
- Preview any restore as a per-file diff before anything changes.
- Restore files only, or restore files and roll the conversation back to the same point.
- Undo a restore, including the conversation turns it removed.
- Clean up what shell commands changed, such as package-lock.json after
npm install, with git. - Stop most bad changes before they happen, with approvals on the CLI, the desktop app and your phone.
How checkpoints work, and what they do not cover
The help text for safeguard checkpoints is short and precise, so it is worth reading slowly. Here is what it says, in plain terms.
What gets saved. Files the agent writes or edits are snapshotted before each change. Each snapshot is a checkpoint. A session can have many, and checkpoints list shows them oldest first.
What a restore does. Restoring a checkpoint puts every file changed since that checkpoint back as it was before it, and removes the files the agent created after it.
What happens to the state you overwrite. It is kept as a new checkpoint. That is why a restore can itself be undone: restoring that new checkpoint puts back the files and the checkpoints the restore removed, and the conversation turns too when the restore rolled the transcript back.
Files only, or files and conversation. By default, a restore also rolls the session's transcript back to the same point, which is what /rewind does inside the terminal. Add --files-only to restore the files and keep the conversation as it is.
Short ids work. You can name a checkpoint by a prefix of its id when only one checkpoint matches.
What is not saved. Anything a shell command writes. This is the line to remember. When the assistant edits package.json, that edit is checkpointed. When it then runs npm install with your approval, npm rewrites package-lock.json and node_modules, and that is a shell command writing files. The npm docs describe package-lock.json as generated automatically for any operation where npm modifies the node_modules tree or package.json. Checkpoints will not bring those back. Git will.
| What changed | Covered by checkpoints | How to undo it |
|---|---|---|
| The assistant edited an existing file | Yes | safeguard checkpoints restore or /rewind |
| The assistant created a new file | Yes, a restore removes it | safeguard checkpoints restore or /rewind |
A command it ran wrote files, such as npm install | No | git restore, then reinstall |
| You edited a file yourself during the session | Not part of the agent's checkpoints | git |
| Something left your machine, such as a push | No | Your normal git and release process |
The recorded session in this guide pushes nothing, and that is the safe default. Undo on your own machine is easy. Undo after a push is a team conversation.
Before you start: set up so undo is easy
A few habits at the start of a session make every later step faster.
- Work in a git repository with a clean tree. Commit, or stash your work in progress. The git docs describe
git stashas recording the current state of the working directory and the index and going back to a clean working directory. Add-uto include untracked files.
git status
git stash push -u -m "before assistant session"
- Give the session an id you will remember.
--session-idpins the new session's id, using letters, digits, dot, dash and underscore.-nor--namenames it. Either one saves you a search later.
cd ~/code/payments-api
safeguard --session-id lodash-fix-1021 -n "lodash upgrade"
-
Pick an approval mode that gives you review points. Type
/permissionsin the terminal. The interactive CLI offers Ask (reads run; edits and commands ask first), Accept edits (edits in this folder and read-only commands run; other commands ask), Plan (read and plan only), Auto (read-only commands and what the policy allows run; anything else asks; the default) and Strict (pre-approved actions only, for CI). For a first session on real code, Ask shows you every edit and command before it happens. There is also a--yoloflag that approves everything; keep it for throwaway sandboxes only. -
Know where your sessions are.
safeguard sessions listlists saved sessions, newest first. Add--allto include archived ones.
safeguard sessions list
If you are new to the CLI, this guide to the assistant on your machine covers install and first session in more depth.
Walkthrough: undo an edit from the command line
The scenario: in the sample payments-api project you asked "fix the lodash CVE in this repo". The assistant edited package.json to move lodash to 4.17.21, then, with your approval, ran npm install and npm test. Now you want to go back to where you started, perhaps to try a different fix, or because you want to land the change in a different branch.
- Find the session id. If you pinned one with
--session-id, you already have it. Otherwise list sessions and copy the newest one for this project.
safeguard sessions list
- List its checkpoints. They print oldest first. The first checkpoint before the package.json edit is the one that takes you back to the start.
safeguard checkpoints list --session lodash-fix-1021
- Preview the restore.
--dry-runchanges nothing. It prints what would change, with a diff per file. Read it. If a file you care about is not in the list, a shell command probably wrote it, and you will handle it with git in step 6.
safeguard checkpoints restore 3f2a --session lodash-fix-1021 --dry-run
Here 3f2a stands for the start of the checkpoint id from step 2. A prefix is enough when only one checkpoint matches.
- Restore the files and keep the conversation. Use
--files-onlywhen the conversation is still useful, for example when you want to ask the assistant to try a different approach with everything it already learned.
safeguard checkpoints restore 3f2a --session lodash-fix-1021 --files-only
- Or restore files and conversation together. Leave out
--files-onlyand the transcript is rolled back to the same point, as/rewinddoes. Choose this when the conversation itself went the wrong way and you want to ask again from a clean point.
safeguard checkpoints restore 3f2a --session lodash-fix-1021
- Clean up what shell commands changed. Checkpoints restored package.json. They did not touch package-lock.json or node_modules, which
npm installrewrote. Check with git and restore the lockfile from your last commit, then reinstall so node_modules matches it again.
git status
git diff --stat
git restore package-lock.json
npm install
The git docs give a fair warning here: restoring the working tree discards uncommitted changes to the paths you name, so check git status and git diff first.
- Confirm you are back. Run the tests, and ask the CLI to review what is left in the working tree.
safeguard reviewreviews the working-tree changes for correctness and security, and--basecompares against a git ref instead.
npm test
safeguard review
safeguard review --base main
For scripts and dashboards, add --json to any checkpoints command to get JSON instead of text.
safeguard checkpoints list --session lodash-fix-1021 --json
Undo inside the interactive terminal with /rewind
Most of the time you will notice a wrong turn while the session is still open. That is what /rewind is for. It works on the same checkpoints as safeguard checkpoints, and like a restore without --files-only, it rolls the conversation back as well as the files.
- Stop the current task if it is still running. Press esc. It interrupts a running task without exiting the CLI.
- Type
/rewind. Choose the checkpoint you want to go back to. - Check the result. Ask "show me the diff of the working tree against HEAD", or run
git diffyourself in another terminal. - Clean up shell side effects. Exactly as in the command line walkthrough: if a command such as
npm installran after that checkpoint, restore the lockfile with git and reinstall. - Ask again, better. A rewind is a chance to tighten the request. "Fix the lodash CVE with the smallest change, and do not touch other dependencies" is a different task from the first one, and you will get a different plan.
The state you rewind away from is kept as a checkpoint, so a rewind can be rewound. If you only want the files back and want to keep the conversation, exit and use safeguard checkpoints restore with --files-only, or come back later with /resume, which picks up the last session in the folder you start in.
Undo the undo, or keep both attempts
Restores are reversible by design, which takes the pressure off.
Undo a restore
- List the checkpoints again. After a restore, the session has a new checkpoint holding the state the restore overwrote.
safeguard checkpoints list --session lodash-fix-1021
- Preview restoring that new checkpoint.
safeguard checkpoints restore 9c71 --session lodash-fix-1021 --dry-run
- Restore it. This puts back the files and the checkpoints the first restore removed. If the first restore rolled the transcript back, the turns come back too.
safeguard checkpoints restore 9c71 --session lodash-fix-1021
The same caveat applies in both directions. Anything a shell command wrote is outside the checkpoint system, so run git status after each step.
Try a different approach without losing the first one
Sometimes you do not want to undo. You want to keep the first attempt and try a second one beside it. Two features from --help cover this.
Fork when you resume. --fork-session, used with --resume or --continue, copies the session into a new one instead of extending it. The original stays as it was.
safeguard --resume=lodash-fix-1021 --fork-session
Fork into its own git worktree. safeguard sessions fork copies a session's transcript into a new session id. Add --worktree to give the copy its own git worktree, so its file changes never mix with your main checkout. Without --background, the copy is just written and you resume it with safeguard agent --resume= followed by the new id.
safeguard sessions fork lodash-fix-1021 --worktree
Two cleanup commands are worth knowing, and worth using carefully. safeguard sessions delete deletes a session, its transcript and its checkpoints. safeguard sessions rm removes a session, its transcript, its log and its worktree. Once a session is gone, so is its way back, so delete only after you have committed what you want to keep.
Stop bad changes before they happen, on every surface
Undo is the safety net. Approvals are the railing. Every change the assistant makes to files or through commands goes through your approval mode, and a CLI session is live: it shows in the web app, the desktop app and the phone app, and other devices can send work to it. From the desktop or phone app you can send work to a computer running the CLI, pick the computer and folder, then approve each command and file edit there.
This recorded desktop session shows that loop. The CLI session appears in the desktop app's conversation list, and "2 connected" shows the computer, the browser and Safeguard cloud. You ask for work on your computer, it asks which computer and folder, you pick the folder, then Approve or Deny each command and file edit. It ends with the upgrade done and tests passing. The desktop app guide covers installing it.
Click through it at your own pace, or open it full screen.
On the phone, the same decisions fit in your hand. In this recorded Android session the same conversations appear on the phone, "Work on my computer" picks a computer running the CLI and a folder, and the command waits for Allow once, Allow for turn or Deny on the phone. The answer shows the tests passed. Deny is the cheapest undo there is.
Click through it at your own pace, or open it full screen.
Before you merge anything an assistant produced, review it. Reviewing AI-generated code before merge walks through that step with safeguard review.
Troubleshooting and common mistakes
Troubleshooting
The checkpoint list is empty. Check the session id with safeguard sessions list, and add --all if the session was archived. If the session only ran commands and never wrote or edited a file itself, there is nothing to list, because shell command writes are not snapshotted. Runs started with --private or --no-session-persistence are not recorded in the session store, so plan to rely on git for those.
A short id is rejected. A prefix works only when one checkpoint matches. Add more characters from checkpoints list.
A file is still changed after a restore. It was probably written by a command, not by the assistant's own edit tool. Lockfiles and build output are the usual cases. Use git status, git diff and git restore on that path.
My own edits disappeared after a restore. A restore puts every file changed since the checkpoint back as it was. The state it overwrote is kept as a new checkpoint, so list checkpoints again and restore the newest one to get your edits back.
The conversation lost turns I wanted. You restored without --files-only, which rolls the transcript back like /rewind. Restore the new checkpoint the restore created and the turns come back. Next time, add --files-only.
safeguard exec refuses to run. It refuses outside a git repository, because there would be no way to undo what it changes. Run it inside a repository. --skip-git-repo-check exists, but you lose the git safety net that this guide relies on.
Something else looks wrong. Run safeguard doctor. It checks everything the agent depends on, prints what is wrong in the order that matters and changes nothing.
Common mistakes
- Treating checkpoints as a replacement for git. They cover the assistant's own writes and edits in one session. Git covers everything, including what commands wrote.
- Restoring without a dry run.
--dry-runcosts nothing and shows a diff per file. Make it a habit. - Forgetting that a full restore rolls the conversation back. Use
--files-onlywhen the conversation is still worth having. - Deleting the session too early.
sessions deleteremoves the checkpoints along with the transcript. Commit first, then clean up. - Running
--yoloon a real repository. It approves everything. Keep it for throwaway sandboxes. - Pushing before you have looked. Checkpoints and
/rewindwork on your machine. Review, test and commit locally, then push.
FAQ
What exactly does a checkpoint save?
The contents of each file the assistant is about to write or edit, taken before the change. It does not save what shell commands write, such as lockfiles, build output or installed packages.
Does /rewind undo the commands the assistant ran?
No. It restores files the assistant wrote or edited and rolls the conversation back. Side effects of commands, such as an npm install, need git and a reinstall.
Can I undo a restore or a rewind?
Yes. The state a restore overwrites is kept as a new checkpoint. Restoring that checkpoint puts back the files and checkpoints the restore removed, and the turns too if the transcript was rolled back.
Where do I find the session id?
Run safeguard sessions list, newest first, or pin your own at the start with --session-id. Checkpoint ids can be shortened to any prefix that matches only one.
Can I use my Claude or ChatGPT plan in these sessions?
Yes. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. Use /model to see or switch the model, and see the CLI docs for connecting one. You can also connect ChatGPT to the Safeguard MCP server to use Safeguard from ChatGPT.
Do I still need git if I have checkpoints?
Yes. Checkpoints make undoing the assistant's edits quick. Git is still the record of the whole working tree, and it is the only way back for files a command changed.
Why does safeguard exec insist on a git repository?
Its help text says so directly: outside a repository there would be no way to undo what it changes. exec runs one assistant turn without prompting, with strict permissions by default, so anything the policy file has not pre-approved is denied.
Can I script restores?
Yes. Every checkpoints command accepts --json, and restore accepts --dry-run and --files-only, so a script can list, preview and restore without anyone typing into the terminal.
Try it yourself
This recorded session is a real CLI run on the sample payments-api project, and it shows the exact edit this guide undoes. It installs with the curl command (checksum verified), runs safeguard --version, and opens the interactive terminal with safeguard. It then asks "fix the lodash CVE in this repo". The assistant reads the finding, files and advisory, then asks before each command (press y or n), edits package.json to lodash 4.17.21, runs npm install and npm test with approval, and prints a summary with a suggested commit message. It pushes nothing. It finishes with /permissions, /model and /scan ..
Click through it at your own pace, or open it full screen.
Get the CLI, the desktop app and the phone apps from safeguard.sh/download, and keep the CLI docs close by. Then run one small fix in a clean repository, and practise the full loop once: list, dry run, restore, undo the restore. After that, letting the assistant edit code stops feeling like a gamble.
Quick check
Which changes do Safeguard CLI checkpoints not cover?
Anything a shell command writes, such as package-lock.json and node_modules after npm install. Use git for those.
How do you restore files but keep the conversation?
Run safeguard checkpoints restore with the checkpoint id, --session and --files-only. Without --files-only the transcript is rolled back too, as /rewind does.
How do you see what a restore would change before running it?
Add --dry-run. It changes nothing and prints what would change, with a diff per file.
Sources
- Safeguard CLI overview
- Safeguard CLI interactive terminal
- Safeguard CLI usage guide
- Safeguard CLI troubleshooting
- Safeguard downloads
- git restore documentation
- git stash documentation
- npm package-lock.json documentation
Last reviewed: 21 October 2026.
