What a snapshot is
A snapshot is an APFS clone of the whole project folder, made with the same copy-on-write feature macOS uses when you duplicate a file in Finder. A clone copies references to the data, not the data, so a large repository is cloned in well under a second and takes almost no extra disk space until files change.
It covers everything in the folder, including what git doesn't track: uncommitted work, .env files, node_modules, build output, local databases and anything in .gitignore.
When snapshots are taken
- When an agent starts. Rollcage watches for
claude,codex,cursor-agent,gemini,aider,opencode,gooseandamp, and you can add your own. - Every 15 minutes while an agent is running. You can change the interval.
- On a fixed schedule, every few hours whether or not an agent is running. This is optional.
- Whenever you press Snapshot now.
With auto-protect on, you don't have to add projects by hand: when an agent starts inside a git repository that isn't protected yet, Rollcage adds it and takes the first snapshot.
See what changed, then restore
Open any snapshot and Rollcage compares it with the folder as it is now, listing the files that were deleted, modified or added since. Restore the files you select, or roll the whole folder back.
Restoring never deletes anything. The current versions are moved to a dated folder in ~/Library/Application Support/Rollcage/Replaced first, so a restore can itself be undone.
The mass-delete alarm
Rollcage watches protected folders for bursts of deletions. When more than 100 files disappear within 10 seconds, or the folder itself is removed, you get a notification that opens the latest snapshot. Both numbers are yours to change. A folder that stays deleted is dropped from the list after one alert, and restoring it protects it again.
Why not just git, or the agent's own undo?
| Covers | Misses | |
|---|---|---|
| git | Committed files | Uncommitted work, ignored files such as .env, and anything after git reset --hard or git clean -f |
| Agent checkpoints | Edits the agent made with its own edit tool | Files changed or deleted by shell commands such as rm, mv or a script the agent ran |
| Time Machine | Hourly backups to another disk | The last hour, and it's slow to browse for one project |
| Rollcage | Every file in the folder, at the moment the agent started | Folders on external disks |
The guides on undoing Claude Code changes and YOLO mode go into the details.
Limits worth knowing
- Snapshots are kept for 7 days or 50 snapshots by default. You can change both.
- Snapshots live on the same disk as your projects, in
~/Library/Application Support/Rollcage/Snapshots. They are an undo button, not a backup: keep using git and Time Machine. - Protected folders must be on the same APFS volume as your home folder. External disks aren't supported yet.
Questions
How much disk space do snapshots use?
Almost none at first. An APFS clone shares its data with the original, so space is only used for files that change afterwards. Old snapshots are removed after 7 days or once there are more than 50, and you can change both limits.
Can I get back files that were never committed to git?
Yes. A snapshot is a copy of the folder on disk, so it includes uncommitted changes, untracked files and files listed in .gitignore.
Does it work with agents other than Claude Code?
Yes. Snapshots and the mass-delete alarm work with any agent, because they watch the process list and the folder, not the agent. Claude Code, Codex CLI, Cursor, Gemini CLI, Aider, OpenCode, Goose and Amp are detected out of the box.
What if the agent deletes the whole project folder?
The alarm fires, and the snapshot is untouched because it's stored outside the project. Restore the folder from the snapshot and Rollcage protects it again.