claude-vigil

name	claude-vigil
description	Use when about to make risky changes — refactors, migrations, destructive bash commands, schema changes, or experimental approaches that might need reverting. Checkpoint project state for safe rollback.

Claude Vigil

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

1. vigil_save(name: "before-refactor") — first save auto-detects derived dirs from .gitignore
2. Make the risky changes
3. vigil_diff(name: "before-refactor") — check what changed
4. If broken: vigil_restore(name: "before-refactor") — then rebuild derived dirs
5. 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