# Claude Vigil

> File checkpoint and recovery — auto-quicksaves before destructive commands, INVOKE before implementing a plan or starting risky multi-file changes. Also use when user asks to undo changes or compare current state to a prior checkpoint.

- Skill: `vvkmnn/claude-vigil` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vvkmnn/claude-vigil`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vvkmnn/claude-vigil/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vvkmnn (https://skillmd.com/u/vvkmnn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vvkmnn/claude-vigil

---


# Vigil Plugin

File recovery. Saves checkpoints before dangerous operations, diffs changes, restores files safely.

## Hooks

| Hook | When | Action |
|------|------|--------|
| **PreToolUse(Bash)** | Destructive command detected | Auto-quicksaves affected files (rm, mv, git reset, etc.) |

Token cost: 0 on safe commands, ~30 on destructive.

## Commands

| Command | Description |
|---------|-------------|
| `/save-vigil <name> [files]` | Create a named file checkpoint |
| `/restore-vigil [name]` | Restore files from a checkpoint |

## Workflows

### Before Implementing a Plan

After exiting plan mode, before writing any code:

1. `vigil_save(name="before-<plan-name>")` — snapshot the project
2. Implement the plan
3. If something goes wrong: `vigil_diff(name="before-<plan-name>")` then `vigil_restore(name="before-<plan-name>")`

### Before Risky Changes

Before refactors or multi-file changes:

1. `vigil_save(name="before-refactor")` — named checkpoint
2. Make changes safely
3. If something breaks: `vigil_diff` first, then `vigil_restore`

### Recovery

Always diff before restoring:

1. `vigil_list()` — see available checkpoints
2. `vigil_diff(name="checkpoint")` — preview what would change
3. `vigil_restore(name="checkpoint")` — restore files
4. Displaced files are preserved in `.claude/vigil/artifacts/`

### Storage Management

Vigil has 3 named slots + 1 rotating `~quicksave`:

- `~quicksave` is ONE rotating slot — overwritten on each destructive command
- Named checkpoints persist until deleted
- Run `vigil_list()` periodically to check capacity
- When nearing capacity (2+ named checkpoints), offer to clean up the oldest with `vigil_delete(name="oldest")`
- `vigil_restore` preserves displaced files in `.claude/vigil/artifacts/` — ask the user before cleaning those up

## MCP Tools Reference

| Tool | Purpose |
|------|---------|
| `vigil_save` | Create named checkpoint (SHA-256 + gzip dedup) |
| `vigil_list` | List available checkpoints with metadata |
| `vigil_diff` | Preview changes since checkpoint |
| `vigil_restore` | Restore files from checkpoint |
| `vigil_delete` | Remove a checkpoint and free storage |

## Requires

```
claude mcp add vigil -- npx claude-vigil-mcp
```