Skip to main content
Glama
Vvkmnn

claude-vigil-mcp

by Vvkmnn
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

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.

claude-vigil-mcp

npm version License: MIT TypeScript Node.js Claude GitHub stars

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:

Claude 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

Related MCP server: Memory Bank MCP

skill

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 <save|list|diff|restore|delete>

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   │  <5ms, returns immediately
              │  (detached)     │
              └────────┬────────┘
                       │
            ┌──────────┴──────────┐
            │   background worker │
            │                     │
            │  ┌───────────────┐  │
            │  │ walk project  │  │  source files only (skips derived dirs)
            │  └───────┬───────┘  │
            │          │          │
            │  ┌───────▼───────┐  │
            │  │ hash (SHA-256)│  │  same content = same hash
            │  └───────┬───────┘  │
            │          │          │
            │  ┌───────▼───────┐  │
            │  │ gzip + store  │  │  dedup: skip if exists
            │  └───────┬───────┘  │
            │          │          │
            │  ┌───────▼───────┐  │
            │  │update manifest│  │  {path → hash} per checkpoint
            │  └───────────────┘  │
            └─────────────────────┘

     ┌─────────────────────────────────────────┐
     │  .claude/vigil/                         │
     │  ├── manifest.json    checkpoints + meta│
     │  ├── objects/                           │
     │  │   ├── ab/cdef01...gz   gzipped file  │
     │  │   ├── f3/981a02...gz   gzipped file  │
     │  │   └── ...              (deduped)     │
     │  └── artifacts/                         │
     │      └── restored_v1.0_20260219_.../    │
     │          ├── src/auth.ts   (modified)   │
     │          └── src/new.ts    (new file)   │
     └─────────────────────────────────────────┘

     3 named slots + 1 rotating quicksave
     Every response: "vigil: 2/3 | quicksave: 3m ago | 287 MB"


     RESTORE (only sync operation):

     vigil_restore("v1.0")
            │
            ├── quicksave current state (overwrite previous)
            │
            ├── preserve displaced files in artifacts/
            │   ├── modified files → copied to artifacts
            │   └── new files → moved to artifacts
            │
            ├── read manifest → get {path → hash}
            │
            ├── for each file: gunzip object → write to project
            │
            └── done: bit-identical working directory

Storage: Content-addressable storage (SHA-256 + gzip). Same file across checkpoints = stored once. Binary files included -- a restored checkpoint is bit-identical to the original.

Performance: Background worker via spawn(detached). MCP tool returns in <5ms. Worker runs independently. Only vigil_restore is synchronous (must write files before Claude proceeds).

Disk honesty: Every tool response shows vigil: 2/3 | quicksave: 3m ago | 273 MB. No hidden costs. 3 checkpoint slots by default. .vigilignore for excluding paths you don't need.

Artifact preservation: On restore, files that would be overwritten or lost (modified since checkpoint, or newly created) are preserved in .claude/vigil/artifacts/. Nothing is ever deleted -- you can always recover displaced work.

                  v1.0        v1.1        v1.2      objects/
                  ━━━━        ━━━━        ━━━━      ━━━━━━━━━━━━━━━━

  src/index.ts    ab3f ══════ ab3f ══════ ab3f  →   ab/3f01a2...gz
  src/auth.ts     f981        e904 ══════ e904  →   f9/81b3c4...gz
                                                    e9/04f7a8...gz
  src/server.ts   2bc4 ══════ 2bc4 ══════ 2bc4  →   2b/c4d5e6...gz
  src/utils.ts    7de1 ══════ 7de1 ══════ 7de1  →   7d/e1f2a0...gz
  src/config.ts   4aa2 ══════ 4aa2        d71c  →   4a/a2b1c3...gz
                                                    d7/1c45e8...gz
                  ────        ────        ────
  new objects:    5           1           1     =   7 (not 15)

  ══════ same SHA-256 across checkpoints -- stored once, referenced many
  save v1.0       ██████████████████████████████████████████████████  100 new
  save v1.1       ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████    8 new
  save v1.2       ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██    3 new
                  ──────────────────────────────────────────────────
                  111 objects store 300 file-versions     2.7× dedup

  delete v1.0     gc sweep → 62 orphans freed, 49 shared retained
                  ░░░░░░░░░░░░░░░░░░░░░░░░░               4.1× dedup

  ████ new object stored    ░░░░ deduped (hash exists, write skipped)

Core techniques:

  • content-addressable storage (storeObject): SHA-256 hash → existsSync check → skip or gzip + write. Same content = same address = automatic dedup.

  • mark-and-sweep GC (gcObjects): Union referenced hashes across all checkpoints, delete orphans, reclaim space.

  • LCS unified diffs (generateUnifiedDiff): O(n×m) longest common subsequence with 3-line context hunks.

  • cross-checkpoint search (diffCheckpoint search mode): Iterate checkpoints → resolve file hash → gunzip → line scan with ±2 context.

  • background snapshots (worker.ts): spawn(detached) with .in-progress lockfile, <5ms return to Claude.

Disk usage: Vigil auto-skips derived directories (node_modules/, dist/, target/, venv/, etc.) detected from .gitignore and common patterns. Only source files are checkpointed.

Project type

Raw size

Source only

First snapshot

Incremental

Next.js app

750 MB

~2 MB

~1 MB

~50 KB

Rust project

2.5 GB

~5 MB

~3 MB

~100 KB

Python project

350 MB

~3 MB

~2 MB

~50 KB

After restore, vigil reports which derived dirs exist but weren't restored -- Claude rebuilds them (npm install, cargo build, etc.). Edit .claude/vigil/.vigilignore to adjust what gets skipped.

Architecture:

claude-vigil-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts       # MCP server, 5 tools
│   ├── types.ts       # TypeScript interfaces and discriminated unions
│   ├── store.ts       # CAS: hash, store, read, gc, disk usage
│   ├── snapshot.ts    # create, restore, diff, list, delete
│   └── worker.ts      # background snapshot process
├── .claude/
│   └── skills/
│       └── claude-vigil/
│           └── SKILL.md   # optional skill for proactive checkpointing
└── test/
    └── index.test.ts  # 73 tests

Design principles:

  • No git dependency -- pure Node.js built-ins (crypto, zlib, fs)

  • Perfect snapshots -- every file captured, no size/binary filtering

  • CAS + gzip -- 3.5x leaner than hard links, automatic dedup

  • Background execution -- Claude never blocks on snapshot creation

  • 3-slot limit -- conservative default prevents runaway storage

  • Stateless server -- reads manifest from disk each call, no in-memory state to lose

  • Artifact preservation -- displaced files saved on restore, nothing ever lost

  • Cross-platform -- macOS, Linux, Windows. No shell dependencies

Design influences:

alternatives

Every existing checkpoint tool -- built-in or third-party -- only tracks file edits made through the editor's own API. When Claude runs sed -i, a Python script overwrites a config, or a build tool corrupts output, those changes are invisible and unrecoverable.

Feature

vigil

/rewind

Rewind-MCP

claude-code-rewind

Checkpoints app

Cursor

Tracks external changes

Yes (bash, scripts, builds)

No

No

No

No

No

Named checkpoints

Yes

No (timestamps)

Yes

Yes

Yes

No

Content diffs

Yes (unified diffs)

No

No

Yes (visual)

No

No

Search across checkpoints

Yes

No

No

No

No

No

Artifact preservation

Yes (nothing lost)

N/A

No

No

No

No

Dedup storage

CAS + gzip

None

Unknown

SQLite + diffs

Full copies

Zip per edit

Background saves

Yes (<5ms return)

Blocking

Blocking

Blocking

Background

Blocking

Headless/programmatic

Yes (MCP)

No (#16976)

Yes (MCP)

CLI

No

No

Cross-platform

Node.js

Built-in

Node.js

Python

macOS only

Built-in

Dependencies

0 (Node built-ins)

N/A

Node.js

Python + SQLite

Desktop app

N/A

Disk visibility

Every response

Hidden

Manual

Manual

Manual

Hidden

Claude Code /rewind -- Built-in checkpoint system. Only tracks file edits made through Claude's own tools -- sed -i, build scripts, and external processes are invisible. No named checkpoints, no content diffs, no search. Blocking saves that pause the session. Not yet available via MCP (#16976).

Rewind-MCP -- Third-party MCP server with stack-based undo. Provides MCP access but doesn't track external changes (bash, scripts, builds). No content diffs, no search across checkpoints, no dedup storage. Blocking saves.

claude-code-rewind -- Python-based snapshot tool with SQLite metadata and visual diffs. Requires Python + SQLite. Doesn't track external changes. No cross-checkpoint search, no artifact preservation, no background saves. CLI-only (no MCP integration).

Checkpoints app -- macOS desktop app that monitors projects for file changes. Background saves but macOS-only, no content diffs, no search, no MCP integration. Stores full copies of each checkpoint (no dedup), so disk usage grows linearly.

Cursor checkpoints -- Built-in to Cursor. Zips project state before each AI edit. No named checkpoints, no content diffs, no search, no external change tracking. Hidden from disk, blocking saves, not programmable.

Three implementation approaches were evaluated before settling on content-addressable storage:

  • Shadow git repo (git --git-dir=.claude/vigil/.git --work-tree=.) -- wraps git for dedup, diff, and restore. 6 failure modes: self-tracking recursion, unbounded binary bloat, concurrent index.lock conflicts, overlay on restore (doesn't delete files added after checkpoint), git clean destroying project files, and GIT_DIR/GIT_WORK_TREE env var interference from parent processes.

  • Hard-link Time Machine pattern -- directory trees with unchanged files hard-linked (zero per-file cost). Battle-tested by macOS Time Machine, but 20 checkpoints of 1000 files = 20,000 directory entries. CAS + gzip is 3.5x leaner and deduplicates content across checkpoints for free.

  • rsync --link-dest -- same hard-link idea in ~30 lines. No built-in diff capability, losing the unified diffs and cross-checkpoint search that make vigil_diff useful.

development

git clone https://github.com/Vvkmnn/claude-vigil-mcp && cd claude-vigil-mcp
npm install && npm run build
npm test

Scripts:

Command

Description

npm run build

TypeScript compilation (tsc && chmod +x dist/index.js)

npm run dev

Watch mode (tsc --watch)

npm start

Run MCP server (node dist/index.js)

npm run clean

Remove build artifacts (rm -rf dist)

npm run lint

ESLint code quality checks

npm run lint:fix

Auto-fix linting issues

npm run format

Prettier formatting

npm run format:check

Check formatting without changes

npm run typecheck

TypeScript validation without emit

npm test

Type-check + lint

npm run prepublishOnly

Pre-publish validation (build + lint + format check)

Pre-commit hooks via husky run lint-staged (prettier + eslint) on staged .ts files.

Contributing:

  • Fork the repository and create feature branches

  • Follow TypeScript strict mode and MCP protocol standards

Learn from examples:

license

MIT

Claudius Proclaimed Emperor by 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.

Available Tools

5 tools
vigil_deleteDelete CheckpointA
Destructive

Delete a checkpoint and reclaim disk space. Use all=true to delete all checkpoints. Note: artifact directories from previous restores are NOT deleted — ask the user if they want you to clean those up separately.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoCheckpoint name to delete
allNoDelete all checkpoints and reclaim all space

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

DestructiveHint annotation already indicates destructive action; description adds value by mentioning disk reclamation and the caveat about artifact directories not being deleted, providing extra behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is very concise with two sentences, no fluff, and covers essential information efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description adequately covers the action and a notable caveat. Could mention irreversibility explicitly, but destructiveHint implies it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for both parameters. Description reinforces 'all' usage but does not add significant meaning beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Delete a checkpoint and reclaim disk space' with a specific verb and resource. It distinguishes itself from siblings (diff, list, restore, save) by the delete action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides clear context for deleting one or all checkpoints using the 'all' parameter, and advises about artifact directories not deleted. However, it does not explicitly state when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vigil_diffCompare StatesA
Read-onlyIdempotent

Search and investigate previous versions of your codebase. Compare checkpoint vs 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 to find when code existed. Use this to find previous versions of files or functions, understand what changed, and pull out whatever snippets or diffs are needed — then apply selectively with Edit.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesCheckpoint name to diff against (use "*" with file+search to scan all checkpoints)
fileNoSpecific file to retrieve from checkpoint (returns content + diff vs current)
summaryNoReturn file list only without content diffs (faster for large changesets)
againstNoCompare against another checkpoint instead of current working directory
searchNoSearch for this string across all checkpoints (requires name="*" and file)

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds rich behavioral context beyond annotations: it mentions 'full unified diffs', the summary option for faster results, and the capability to search across checkpoints. Annotations already indicate readOnly and idempotent, and the description does not contradict these. It fully informs the agent of safe, stateless behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that front-load the overall purpose and then enumerate specific capabilities without redundancy. Every word serves a purpose, and the structure is clear and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple operations, 5 parameters, no output schema), the description covers the core functionality well, explaining key parameter interactions and use cases. It does not detail return format or error handling, but enough context is provided for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, baseline is 3. The description enhances parameter understanding with usage hints: e.g., name can be '*' for scanning, search requires name='*' and file, against enables cross-checkpoint comparison. This adds meaningful context beyond the schema's brief descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the tool's purpose: to search and investigate previous versions of the codebase by comparing checkpoints or retrieving file contents. It distinguishes itself from sibling tools like vigil_delete, vigil_list, vigil_restore, and vigil_save through its focus on diffing and historical retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage scenarios: comparing checkpoints, retrieving file contents, and searching across checkpoints. It mentions parameter interactions (e.g., '*' with file+search for scanning all checkpoints). It lacks explicit when-not-to-use guidance but sufficiently implies that this tool is for investigation, not deletion or saving.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vigil_listList CheckpointsA
Read-onlyIdempotent

List all checkpoints and disk usage. With name: list files inside that checkpoint.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoCheckpoint name to drill into (omit for overview)
globNoGlob pattern to filter files (e.g., "src/auth/**")

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. Description adds that it shows disk usage and has dual behavior based on name, which aligns with annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with main function, then variation for name. Every word earns its place; no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-param tool with no output schema, description covers the main behaviors and mentions disk usage. Lacks details on output format or glob usage context, but sufficient for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing baseline of 3. The description adds semantic context for the 'name' parameter (drill into checkpoint) beyond the schema, justifying a score of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists checkpoints and disk usage, with specific behavior when a name is provided (drill into files). This distinguishes it from sibling tools (delete, diff, restore, save) and uses a specific verb+resource combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage: omit name for overview, provide name to list files. It does not explicitly exclude alternatives or mention when not to use, but sibling tools cover other actions, making the context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vigil_restoreRestore CheckpointA
Destructive

Restore project to a checkpoint state. Quicksaves current state first. Displaced files (modified + new) are preserved in .claude/vigil/artifacts/ — nothing is ever deleted. For individual file/function restores, use vigil_diff to get the content and apply with Edit.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesCheckpoint name to restore

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds important context beyond the destructiveHint annotation: explains quicksave and that files are never deleted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three precise sentences with main action first, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and destructive annotation, the description covers behavior, safety, and alternatives fully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter has clear schema description ('Checkpoint name to restore'); tool description adds no additional nuance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Restore project to a checkpoint state' and distinguishes from sibling tool vigil_diff for individual file restores.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions that quicksave occurs first, files are preserved, and directs to vigil_diff for individual restores.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vigil_saveSave CheckpointA
Idempotent

Create a named checkpoint of the entire project. Runs in background — returns immediately. If slots are full, DO NOT auto-retry — ask the user whether to delete an existing checkpoint or increase capacity.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesCheckpoint name (e.g., "before-refactor", "v1.0")
descriptionNoWhat this checkpoint captures (shown in vigil_list)
max_checkpointsNoIncrease the maximum number of checkpoint slots (default: 3)

TDQS

A4.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description says 'Runs in background — returns immediately,' adding behavioral context beyond annotations. However, the idempotentHint: true annotation conflicts with the verb 'Create,' which typically implies non-idempotent behavior. The description does not clarify idempotency, creating a contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first defines core action, second gives critical usage warning. No redundancy, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main behavior (background) and capacity handling. Lacks mention of return value or success/error indications, but no output schema is present. Reasonably complete given sibling context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds context: 'named checkpoint' hints at the 'name' parameter, and the full-slots warning relates to 'max_checkpoints.' No additional details on 'description' parameter are given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a named checkpoint of the entire project,' specifying verb and resource. It differentiates from sibling tools like vigil_delete, vigil_diff, vigil_list, and vigil_restore by focusing on creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs the agent: if slots are full, DO NOT auto-retry but ask the user to delete or increase capacity. This provides clear when-not-to-use and alternative actions, though does not compare to siblings directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.3
    • First observedvigil_delete
    • First observedvigil_diff
    • First observedvigil_list
    • First observedvigil_restore
    • First observedvigil_save
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct operation on checkpoints: save, list, diff, restore, delete. There is no functional overlap, and descriptions clearly differentiate them.

Naming Consistency5/5

All tools follow the 'vigil_verb' pattern with snake_case (e.g., vigil_save, vigil_list). The naming convention is uniform and predictable.

Tool Count5/5

With 5 tools, the server is well-scoped for checkpoint management. Each tool covers a core function without redundancy or missing essential operations.

Completeness5/5

The tool set provides full lifecycle coverage: create (save), read (list), inspect (diff), update (restore), and delete. No obvious gaps for the domain of checkpoint management.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Memory Bank MCP

    spideynolove
    A
    license
    C
    quality
    D
    maintenance
    An MCP server that enables persistent memory, structured thinking sessions, and project-based knowledge management for Claude. It includes specialized coding tools for package discovery and reinvention prevention by validating code against existing libraries and APIs.
    17
    3
    -

  • Claude Memory

    AmmarJawad
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides Claude Code with persistent memory across sessions, including session checkpoints, image persistence, and bidirectional sync with claude.ai projects.
    1
    MIT

  • AgentOps Guardian MCP

    RZFL
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that provides on-demand safety for AI coding workflows, enabling inspection, review, checkpointing, and rollback of risky actions.
    17
    1
    MIT