Cursor Guard

Protects your code from accidental AI overwrite or deletion in Cursor.

中文文档

What It Does

When Cursor's AI agent edits your files, there's a risk of accidental overwrites, deletions, or loss of work. Cursor Guard enforces a safety protocol:

• Mandatory pre-write snapshots — Git commit or shadow copy before any destructive operation
• Read before Write — The agent must read a file before overwriting it
• Review before apply — Diff previews and explicit confirmation for dangerous ops
• Deterministic recovery — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history)
• Configurable scope — Protect only what matters via .cursor-guard.json
• Secrets filtering — Sensitive files (.env, keys, certificates) are auto-excluded from backups
• Auto-backup script — A cross-platform watcher (Node.js) that periodically snapshots to a dedicated Git branch without disturbing your working tree
• MCP tool calls (optional) — 7 structured tools (diagnostics, snapshot, restore, status, etc.) with JSON responses and lower token cost
• Auto-fix diagnostics — doctor_fix automatically patches missing configs, uninitialized Git repos, gitignore gaps, and stale locks

Installation

Method 1: npm

npm install cursor-guard

After installation, copy the skill files to your Cursor skills directory:

Windows (PowerShell):

# Global (all projects)
Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"

# Per-project (current project only)
Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard

macOS / Linux:

# Global
cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard

# Per-project
cp -r node_modules/cursor-guard .cursor/skills/cursor-guard

After copying, you can remove the npm dependency if you don't need it in node_modules:

npm uninstall cursor-guard

Method 2: Git clone

# Global
git clone https://github.com/zhangqiang8vipp/cursor-guard.git ~/.cursor/skills/cursor-guard

# Per-project
git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cursor-guard

Method 3: Manual download

Download from GitHub Releases and extract to:

~/.cursor/skills/cursor-guard/               # Global
<project-root>/.cursor/skills/cursor-guard/   # Per-project

Verify Installation

After installation, your directory structure should look like this:

.cursor/skills/cursor-guard/
├── SKILL.md                            # AI agent instructions (with MCP dual-path logic)
├── ROADMAP.md                          # Version evolution roadmap
├── README.md
├── README.zh-CN.md
├── LICENSE
├── package.json
└── references/
    ├── lib/
    │   ├── auto-backup.js              # Backup watcher (calls Core)
    │   ├── guard-doctor.js             # Health check CLI (calls Core)
    │   ├── utils.js                    # Shared utilities
    │   └── core/                       # V3 Core layer (pure logic)
    │       ├── doctor.js               # Diagnostics (incl. MCP self-check)
    │       ├── doctor-fix.js           # Auto-fix common issues
    │       ├── snapshot.js             # Git snapshots + shadow copies
    │       ├── backups.js              # Backup listing + retention
    │       ├── restore.js              # Single file / project restore
    │       └── status.js               # Backup system status
    ├── mcp/
    │   └── server.js                   # MCP Server (7 tools)
    ├── bin/
    │   ├── cursor-guard-backup.js      # CLI: npx cursor-guard-backup
    │   ├── cursor-guard-doctor.js      # CLI: npx cursor-guard-doctor
    │   └── cursor-guard-mcp (server.js)# CLI: npx cursor-guard-mcp
    ├── auto-backup.ps1 / .sh           # Thin wrappers
    ├── guard-doctor.ps1 / .sh
    ├── recovery.md                     # Recovery commands
    ├── cursor-guard.example.json       # Example config
    ├── cursor-guard.schema.json        # Config schema
    ├── config-reference.md             # Config docs (EN)
    └── config-reference.zh-CN.md       # Config docs (CN)

The skill activates automatically when the AI agent detects risky operations or when you mention recovery-related terms. No extra setup needed.

Quick Start

1. Install the skill using any method above

2. Open Cursor and start an Agent conversation

3. The skill works automatically — when the AI agent tries to edit files, it will:

   • Create a Git snapshot before writing
   • Read files before overwriting
   • Show diff previews for dangerous operations
   • Report a status block after each protected operation

4. (Optional) Add project config to customize protection scope:

cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guard.json

5. (Optional) Enable MCP tool calls — add to .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-guard": {
      "command": "node",
      "args": ["<skill-path>/references/mcp/server.js"]
    }
  }
}

This gives the AI agent 7 structured tools (diagnostics, snapshot, restore, etc.) with JSON responses — faster, more reliable, and lower token cost. Everything works without MCP too.

6. (Optional) Run auto-backup in a separate terminal:

npx cursor-guard-backup --path /my/project

Project Configuration

Edit .cursor-guard.json to define which files to protect:

{
  "protect": ["src/**", "lib/**", "package.json"],
  "ignore": ["node_modules/**", "dist/**"],
  "auto_backup_interval_seconds": 60,
  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
  "pre_restore_backup": "always",
  "retention": { "mode": "days", "days": 30 }
}

pre_restore_backup — restore behavior control

Regardless of config, you can always override per-request:

• Say "don't preserve current version" to skip even when config is "always"
• Say "preserve current first" to force even when config is "never"

Auto-Backup Script

Run in a separate terminal while working in Cursor. Cross-platform — requires Node.js >= 18.

Important:

• You can run the command from any directory
• But --path must point to the project root you want to protect
• If you are already in the project root, --path . is fine
• If you are not in the project root, do not use --path .; use the full target path instead

# If you are already in the project root
npx cursor-guard-backup --path .

# If you are not in the project root
npx cursor-guard-backup --path /my/project
npx cursor-guard-backup --path /my/project --interval 30

# Windows PowerShell
.\references\auto-backup.ps1 -Path "D:\MyProject"

# macOS / Linux
./references/auto-backup.sh /my/project

Wrong example:

# You are in some other directory
# In that case --path . protects the current directory, not your real project
npx cursor-guard-backup --path .

The script uses Git plumbing commands to snapshot to refs/guard/auto-backup — it never switches branches or touches your working index. The ref lives outside refs/heads/ so git push --all won't push it. Supports shadow mode for non-Git directories.

Health Check

npx cursor-guard-doctor --path /my/project

# Windows: .\references\guard-doctor.ps1 -Path "D:\MyProject"
# macOS/Linux: ./references/guard-doctor.sh /my/project

Note: Run backup/doctor scripts in a separate terminal, NOT inside Cursor's integrated terminal.

Recovery

If something goes wrong, just tell the AI agent in natural language.

Default behavior: Before any restore, the agent automatically preserves your current version so you can undo the restore if needed. You don't need to ask for this — it happens by default. To skip, explicitly say "don't preserve current version" or "skip backup before restore".

By time

"restore to 5 minutes ago" "go back to yesterday's version" "restore to 3pm today"

By version

"undo the last change" "go back 3 versions" "restore to the previous version"

By file

"restore src/app.py to 10 minutes ago" "restore src/app.py to the previous version"

The agent will:

1. Preserve your current version first (unless you opt out)
2. Search Git history and auto-backup snapshots
3. Show matching versions for you to choose
4. Restore after your confirmation
5. Report both the pre-restore backup ref and the restore result

If the pre-restore backup fails, the agent will not proceed — it will wait for your explicit confirmation before restoring without a safety net.

Recovery priority

1. Git — git restore, git reset, git reflog
2. Auto-backup ref — refs/guard/auto-backup
3. Shadow copies — .cursor-guard-backup/<timestamp>/
4. Conversation context — Original file content captured by agent Read calls
5. Editor history — VS Code/Cursor Timeline (auxiliary)

See references/recovery.md for detailed commands.

Trigger Keywords

The skill activates on these signals:

• File edits, deletes, renames by the AI agent
• Recovery requests: "rollback", "undo", "recover", "restore"
• Time-based recovery: "restore to N minutes ago", "go back to yesterday"
• Version-based recovery: "previous version", "go back N versions"
• History issues: checkpoints missing, Timeline not working, save failures
• Health check: "guard doctor", "check guard setup", "is MCP working"
• Auto-fix: "guard fix", "fix config"
• Backup status: "guard status", "is the watcher running", "last backup time"

Files

Known Limitations

• Binary files: Git diffs and snapshots work on text files. Binary files (images, compiled assets) are stored but cannot be meaningfully diffed or partially restored.
• Untracked files: Files never committed to Git cannot be recovered from Git history. Shadow copy (backup_strategy: "shadow" or "both") is the only safety net for untracked files.
• Concurrent agents: If multiple AI agent threads write to the same file simultaneously, snapshots cannot prevent race conditions. Avoid parallel edits to the same file.
• External tools modifying the index: Tools that alter Git's index (e.g. other Git GUIs, IDE Git integrations) while auto-backup is running may conflict. The script uses a temporary index to minimize this, but edge cases exist.
• Git worktree: The auto-backup script supports worktree layouts (git rev-parse --git-dir), but has not been tested with all exotic setups (e.g. --separate-git-dir).
• Cursor terminal interference: Cursor's integrated terminal injects --trailer flags into git commit commands, which breaks plumbing commands like commit-tree. Always run auto-backup in a separate terminal window.
• Large repos: For very large repositories, git add -A in the backup loop may be slow. Use protect patterns in .cursor-guard.json to narrow scope.

Requirements

• Node.js >= 18 — core runtime for backup and health check scripts
• Git — for primary backup strategy (not needed for shadow-only mode)
• Cursor IDE — with Agent mode enabled

License

MIT