Claude Vigil Mcp

claude-vigil-mcp

An Model Context Protocol (MCP) server for checkpoint, snapshot, and file recovery in Claude Code. Perfect snapshots, selective restore, bash safety net, and honest disk management.

[](https://www.npmjs.com/package/claude-vigil-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](#) [](https://github.com/Vvkmnn/claude-vigil-mcp)

---

Every AI coding tool tracks file edits made through its own editor, but none of them track file changes made externally: bash commands (rm, mv, sed -i), Python scripts, build tools, or any process that modifies files outside the editor's API. When those changes go wrong, there's nothing to rewind to. Claude Code's built-in /rewind has additional gaps -- external changes are invisible (#6413, #10077), rewind is all-or-nothing with no selective file restore, timestamps only with no named checkpoints, and reliability bugs (#21608, #18516).

install

Requirements:

[](https://claude.ai/code)

From shell:

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

From inside Claude (restart required):

Add this to our global mcp config: npx claude-vigil-mcp

Install this mcp: https://github.com/Vvkmnn/claude-vigil-mcp

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "claude-vigil-mcp": {
      "command": "npx",
      "args": ["claude-vigil-mcp"],
      "env": {}
    }
  }
}

There is no npm install required -- no external databases, no indexing, only Node.js built-ins for crypto, compression, and filesystem.

However, if npx resolves the wrong package, you can force resolution with:

npm install -g claude-vigil-mcp

[skill](.claude/skills/claude-vigil)

Optionally, install the skill to teach Claude when to proactively checkpoint before risky work:

npx skills add Vvkmnn/claude-vigil-mcp --skill claude-vigil --global
# Optional: add --yes to skip interactive prompt and install to all agents

This makes Claude automatically save checkpoints before destructive bash commands, risky refactors, or context compaction. The MCP works without the skill, but the skill improves discoverability.

plugin

For automatic checkpointing with hooks and commands, install from the claude-emporium marketplace:

/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-vigil@claude-emporium

The claude-vigil plugin provides:

Hooks (background, zero-latency):

• PreToolUse (Bash) - auto-quicksave before destructive commands (rm, mv, sed -i, git checkout, git reset)
• PreCompact - auto-checkpoint before context compaction, both manual (/compact) and automatic
• Stop - auto-checkpoint after Claude finishes a response that included file edits
• PostToolUse (Write|Edit) - checkpoint after file modifications
• SessionEnd - last-chance checkpoint when the session terminates

Command: /checkpoint

Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.

features

5 tools. Perfect snapshots. Content diffs. Safe restores with artifact preservation.

vigil_save

Create a named checkpoint of the entire project. Optional description for annotation. If slots are full, Claude asks the user whether to delete an existing checkpoint or increase capacity.

🏺 ┏━ saved "before-refactor" ━━ 47 files · 4.2 MB ━━ vigil: 2/3 | quicksave: 8m ago | 4.2 MB
   ┗ skipped: node_modules, dist, .next

First save auto-detects derived directories from .gitignore and creates .vigilignore:

🏺 ┏━ saved "v1.0" ━━ 47 files · 4.1 MB ━━ vigil: 1/3 | quicksave: none | 4.1 MB
   ┃ skipped: node_modules, dist, .next
   ┃ first save -- confirm these exclusions look correct
   ┗ edit .claude/vigil/.vigilignore to adjust

When slots are full:

🏺 ┏━ 3/3 full -- ask the user before proceeding ━━ vigil: 3/3 | quicksave: 2m ago | 8.7 MB
   ┃ v1.0 (2h ago) · before-refactor (45m ago) · experiment (5m ago)
   ┗ ASK the user: delete one with vigil_delete, or increase capacity with max_checkpoints?

vigil_list

Browse checkpoints with descriptions. With name: drill into that checkpoint's files. With glob: filter files by pattern.

🏺 ┏━ 2 checkpoints ━━ vigil: 2/3 | quicksave: 3m ago | 8.7 MB
   ┃ v1.0                2h ago    47 files
   ┃   Initial stable release
   ┃ before-refactor     45m ago   47 files
   ┃   Snapshot before risky auth changes
   ┗ ~quicksave          3m ago

Drill into a checkpoint with glob filtering:

vigil_list name="v1.0" glob="src/auth/**"

🏺 ┏━ v1.0 ━━ 3 of 47 files matching src/auth/** ━━ vigil: 2/3 | quicksave: 3m ago | 8.7 MB
   ┃ src/auth/index.ts
   ┃ src/auth/middleware.ts
   ┗ src/auth/types.ts

vigil_diff

Search and investigate previous versions of your codebase. Compare a checkpoint against the current working directory with full unified diffs, compare two checkpoints against each other, retrieve any file's content from any checkpoint, or search for a string across all checkpoints.

Summary of changes:

vigil_diff name="before-refactor" summary=true

🏺 ┏━ 3 changes vs before-refactor ━━ vigil: 2/3 | quicksave: 3m ago | 8.7 MB
   ┃ modified  src/auth.ts (+8 -2)
   ┃ modified  src/middleware/validate.ts (+3 -1)
   ┗ added     src/services/oauth.ts

Full unified diffs:

vigil_diff name="before-refactor"

🏺 ┏━ 3 changes vs before-refactor ━━ vigil: 2/3 | quicksave: 3m ago | 8.7 MB
   ┃ modified  src/auth.ts (+8 -2)
   ┃ modified  src/middleware/validate.ts (+3 -1)
   ┗ added     src/services/oauth.ts

━━ src/auth.ts ━━
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -12,6 +12,8 @@
 import { validateToken } from './utils';
-function authenticate(req: Request) {
+function authenticate(req: Request, options?: AuthOptions) {
+  if (options?.skipValidation) return true;
   const token = req.headers.authorization;

Retrieve a single file from a checkpoint:

vigil_diff name="v1.0" file="src/auth.ts"

🏺 ━━ src/auth.ts from v1.0 ━━
import { validateToken } from './utils';
function authenticate(req: Request) {
  const token = req.headers.authorization;
  ...

━━ diff vs current ━━
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -12,6 +12,8 @@
-function authenticate(req: Request) {
+function authenticate(req: Request, options?: AuthOptions) {

Compare two checkpoints:

vigil_diff name="v1.0" against="before-refactor"

Shows unified diffs between the two checkpoint states -- no working directory involved.

Search across all checkpoints:

vigil_diff name="*" file="src/auth.ts" search="validateToken"

🏺 ┏━ "validateToken" in src/auth.ts ━━ 2 checkpoints ━━ vigil: 2/3 | quicksave: 3m ago | 8.7 MB
   ┃ v1.0 (2h ago)
   ┃   import { validateToken } from './utils';
   ┃ before-refactor (45m ago)
   ┗   import { validateToken } from './utils';

vigil_restore

Restore the project to a checkpoint state. Quicksaves current state first (undo with vigil_restore name="~quicksave"). Displaced files -- both modified and newly created since the checkpoint -- are preserved in .claude/vigil/artifacts/ so nothing is ever lost. For individual file restores, use vigil_diff to retrieve file content, then apply with Edit.

vigil_restore name="v1.0"

🏺 ┏━ restored from "v1.0" ━━ 47 files ━━ vigil: 2/3 | quicksave: just now | 8.7 MB
   ┃ preserved 3 displaced files in .claude/vigil/artifacts/restored_v1.0_20260219_143022/
   ┃   modified: src/auth.ts (current version saved)
   ┃   modified: src/middleware/validate.ts (current version saved)
   ┃   new: src/services/oauth.ts (moved, not in checkpoint)
   ┃ review .claude/vigil/artifacts/restored_v1.0_20260219_143022/ -- delete when no longer needed
   ┃ previous state also quicksaved (use ~quicksave to undo)
   ┃ not restored (derived): node_modules, dist
   ┗ rebuild these before running the project

vigil_delete

Delete a checkpoint and reclaim disk space. GC removes unreferenced objects. Use all=true to delete everything.

vigil_delete name="v1.0"

🏺 ━━ deleted v1.0 ━━ reclaimed 241 MB (3,412 objects) ━━ vigil: 1/3 | quicksave: 3m ago | 4.5 MB

methodology

How claude-vigil-mcp stores checkpoints:

                    🏺 claude-vigil-mcp
                    ━━━━━━━━━━━━━━━━━━━

              Claude calls tool
                vigil_save
                    │
                    ▼
              ┌─────────────────┐
              │  spawn worker   │  

_**[Claudius Proclaimed Emperor](https://en.wikipedia.org/wiki/Claudius#/media/File:Lebayle_-_Claudius.jpg)** by **[Charles Lebayle](https://en.wikipedia.org/wiki/Charles_Lebayle)** (1886). Claudius expanded the Vigiles Urbani from firefighters into Rome's night watch -- guardians who patrolled the city, preserved order, and ensured nothing was lost to the dark._

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** [Vvkmnn/claude-vigil-mcp](https://github.com/Vvkmnn/claude-vigil-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.