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 PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree

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
├── README.md
├── LICENSE
└── references/
    ├── auto-backup.ps1               # Auto-backup script
    ├── recovery.md                   # Recovery commands
    ├── cursor-guard.example.json     # Example config
    └── cursor-guard.schema.json      # Config schema

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) Run auto-backup in a separate terminal:

.\auto-backup.ps1 -Path "D:\MyProject"

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"],
  "retention": { "mode": "days", "days": 30 }
}

Auto-Backup Script

Run in a separate terminal while working in Cursor:

.\auto-backup.ps1 -Path "D:\MyProject"

# Custom interval (default 60s):
.\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30

The script uses Git plumbing commands to snapshot to cursor-guard/auto-backup branch — it never switches branches or touches your working index.

Note: Run this script in a separate PowerShell window, NOT inside Cursor's integrated terminal. Cursor's terminal may interfere with Git plumbing commands.

Recovery

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

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 automatically search Git history and auto-backup snapshots, show you matching versions to choose from, and restore after your confirmation.

Recovery priority

1. Git — git restore, git reset, git reflog
2. Auto-backup branch — cursor-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

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.ps1 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.ps1 in a separate PowerShell 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

• Git — for primary backup strategy
• PowerShell 5.1+ — for auto-backup script (Windows built-in)
• Cursor IDE — with Agent mode enabled

License

MIT