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

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
├── README.zh-CN.md
├── LICENSE
├── package.json
└── references/
    ├── lib/
    │   ├── auto-backup.js              # Backup core (Node.js)
    │   ├── guard-doctor.js             # Health check core
    │   └── utils.js                    # Shared utilities
    ├── bin/
    │   ├── cursor-guard-backup.js      # CLI entry: npx cursor-guard-backup
    │   └── cursor-guard-doctor.js      # CLI entry: npx cursor-guard-doctor
    ├── 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) 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.

# Via npx (after npm install)
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

The script uses Git plumbing commands to snapshot to cursor-guard/auto-backup branch — it never switches branches or touches your working index. 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 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 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