Checkpoint project state before risky work. Restore if things break.
When to Use
- Before refactors, migrations, or large code changes
- Before destructive operations (file deletions, schema changes)
- Before experimenting with approaches you might revert
- Before
rm,mv,sed -i,git checkout,git reset - When the user asks to "save state" or "checkpoint"
Quick Reference
| Tool | Purpose |
|---|---|
vigil_save |
Create named checkpoint — background, returns in <5ms |
vigil_list |
Show all checkpoints with disk usage |
vigil_diff |
Compare current state to a checkpoint |
vigil_restore |
Revert to checkpoint — quicksaves current state first, preserves displaced files |
vigil_delete |
Remove a checkpoint and reclaim space |
Workflow
vigil_save(name: "before-refactor")— first save auto-detects derived dirs from.gitignore- Make the risky changes
vigil_diff(name: "before-refactor")— check what changed- If broken:
vigil_restore(name: "before-refactor")— then rebuild derived dirs - If good:
vigil_delete(name: "before-refactor")— reclaim space
After Restore
Vigil skips derived directories (node_modules, dist, target, venv). Read the output — it lists what needs rebuilding. Run the project's install and build commands.
Slot Management
Default: 3 checkpoint slots. When full, delete old checkpoints or increase capacity via max_checkpoints parameter.
Common Mistakes
| Mistake | Fix |
|---|---|
| Forgetting to rebuild after restore | Read vigil's output — it lists what needs rebuilding |
| Restoring without checking diff first | Use vigil_diff to see what will change |
| Not saving before destructive bash | Save before rm, mv, sed -i, git checkout, git reset |