File Shield - VSCode Extension

Automatic backup of all file changes (manual and programmatic) with instant recovery.

Protect your code from accidental overwrites by AI coding assistants, extensions, and manual edits. File Shield automatically backs up every file change with smart exclusions and easy recovery.

Problem

VSCode's Timeline and LocalHistory extensions don't capture programmatic file changes made by extensions (like Claude Code, GitHub Copilot, etc.). This means you can lose work if an extension accidentally deletes or corrupts your files.

Solution

File Shield captures all file changes - both manual edits and programmatic modifications - by listening to both document save events and file system change events.

Features

🛡️ Comprehensive Protection

Dual Event Listening: Captures both manual edits and programmatic changes from AI assistants
Automatic Backups: Every file change is automatically backed up with timestamp
Workspace-Only: Only backs up files inside your project (excludes temp files and external changes)

📁 Smart Organization

Nested Directory Tree: Organize backups by folder structure, just like VSCode Explorer
.gitignore Integration: Automatically respects your .gitignore patterns - no redundant node_modules backups
Custom Exclusions: Add additional patterns beyond .gitignore if needed

🎯 Easy Management

Visual History Browser: TreeView in Explorer sidebar showing all backed-up files
One-Click Restore: Restore any previous version with a single click
Diff View: Compare any backup with current version
Bulk Deletion: Delete backups for entire directories or individual files
Copy Backup Path: Get file path for sharing with Claude or other tools

⚙️ Retention Control

Automatic Cleanup: Old backups are automatically deleted based on retention days
Per-File Limits: Maximum number of backups per file to save disk space
Debouncing: Prevents duplicate backups from rapid successive changes

Installation

Install directly from the VSCode Marketplace:

Open VSCode
Go to Extensions (Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux)
Search for "File Shield"
Click Install

The extension will activate automatically when you open a workspace.

Usage

Viewing Backups

The File Shield Backups panel appears in the Explorer sidebar:

📁 src (15 files, 45 backups)
  📁 components (8 files, 30 backups)
    📄 Button.tsx (5 backups)
    📄 Input.tsx (3 backups)
  📁 utils (7 files, 15 backups)
📄 package.json (3 backups)

Expand directories to see files inside
Click a file to see all backup versions with timestamps
Click a backup version to open diff view

Restoring a Backup

In the "File Shield Backups" panel, navigate to your file
Expand to see backup versions (e.g., "30/03/2026, 16:53:13 (11 B)")
Click the restore icon (🔄) next to the version you want
Confirm restoration
The file will be restored and opened

Deleting Backups

Delete entire directory:

Right-click a folder → Click trash icon or "Clear All Backups in This Directory"
Removes all backups for all files in that directory

Delete individual file:

Right-click a file → Click trash icon or "Clear Backups for This File"
Removes all backup versions for that specific file

Delete all backups:

Cmd+Shift+P → "File Shield: Clear All Backups"

Working with Claude or AI Assistants

Copy backup path to share with Claude:

Expand a file to see backup versions
Right-click a specific backup version
Select "Copy Backup File Path"

Paste in your prompt to Claude:

Claude, please review this previous version:
/Users/.../globalStorage/.../backups/.../file.bak

Open backup directory in Finder/Explorer:

Cmd+Shift+P → "File Shield: Open Backup Directory"
Browse all backups directly in your file system

Commands

Command	Description
`File Shield: Show File History`	Refresh the backups panel
`File Shield: Clear All Backups`	Delete all backups (with confirmation)
`File Shield: Open Backup Directory`	Open backup folder in Finder/Explorer
`Copy Backup File Path`	Copy path of a specific backup (right-click menu)

Status Bar

The status bar shows 🛡️ File Shield when protection is active. Click it to refresh the backup view.

Configuration

Access settings via Cmd+, (or Ctrl+,) → search "File Shield":

`fileShield.enabled`

Type: boolean
Default: true
Enable/disable automatic backups

`fileShield.retentionDays`

Type: number
Default: 7
Number of days to keep backups before automatic deletion

`fileShield.maxBackupsPerFile`

Type: number
Default: 50
Maximum number of backup versions per file

`fileShield.excludePatterns`

Type: array
Default: [] (empty - uses .gitignore)
Additional file patterns to exclude from backups beyond .gitignore
Uses glob patterns: **/*.log, temp/**, etc.

Note: File Shield automatically reads your .gitignore file and excludes those patterns. Use excludePatterns only for additional exclusions not in .gitignore.

How It Works

Smart Exclusion System

File Shield uses a three-layer exclusion system:

Workspace Boundary: Only files inside your project folder are backed up (excludes temp files, external tools, etc.)
.gitignore Patterns: Automatically reads and applies your .gitignore rules
Custom Patterns: Additional exclusions from fileShield.excludePatterns setting

This means you typically don't need to configure anything - it just works!

Dual Event System

File Shield uses two complementary event listeners:

onDidSaveTextDocument: Triggered when files are saved manually or through standard editor operations
FileSystemWatcher: Triggered by file system operations, including programmatic writes by extensions

This dual approach ensures no file change goes untracked, whether it's from you or an AI assistant.

Backup Storage

Backups are stored in VSCode's global storage directory:

Mac:

~/Library/Application Support/Code/User/globalStorage/anatoliihusakovskyi.file-shield/backups/

Windows:

%APPDATA%\Code\User\globalStorage\anatoliihusakovskyi.file-shield\backups\

Linux:

~/.config/Code/User/globalStorage/anatoliihusakovskyi.file-shield/backups/

Each workspace has a separate backup directory identified by a hash of the workspace path.

File Organization

backups/
├── <workspace-hash>/
│   ├── files/                    # Actual backup files
│   │   ├── src_Button_tsx/
│   │   │   ├── 1711814593000.bak
│   │   │   └── 1711814623000.bak
│   │   └── package_json/
│   │       └── 1711814600000.bak
│   └── metadata/                 # Backup metadata (JSON)
│       ├── src_Button_tsx.json
│       └── package_json.json

Debouncing

To prevent duplicate backups from rapid successive changes (e.g., auto-save + extension edit), File Shield debounces changes with a 1-second window per file.

Troubleshooting

No backups appearing

Check extension is enabled: fileShield.enabled should be true
Check file location: Only files inside your workspace folder are backed up
Check exclusions:
- Is the file in .gitignore?
- Is it matched by a pattern in fileShield.excludePatterns?
Check console: Help → Toggle Developer Tools → Console tab → look for [File Shield] messages

Files still being backed up despite being in .gitignore

Old backups: Files backed up before you added them to .gitignore remain. Delete them manually.
Reload required: Reload VSCode after changing .gitignore
Check console: Verify gitignore patterns were loaded (should see [File Shield] Loaded X patterns from .gitignore)

Extension not activating

Workspace required: File Shield requires a workspace folder to be open
Check for errors: Help → Toggle Developer Tools → Console → look for red errors
Reinstall: Uninstall and reinstall the extension

High disk usage

Reduce retention: Lower fileShield.retentionDays (e.g., from 7 to 3 days)
Reduce per-file limit: Lower fileShield.maxBackupsPerFile (e.g., from 50 to 20)
Add exclusions: Add large file patterns to .gitignore or fileShield.excludePatterns
Clear old backups: Use File Shield: Clear All Backups command
Delete specific directories: Right-click large folders in the backup panel → delete

Why This Extension Was Created

Standard VSCode Timeline and LocalHistory extensions only listen to onDidSaveTextDocument events, which aren't triggered by programmatic file writes. This means when extensions like Claude Code, GitHub Copilot, Cursor, or any other AI coding assistant modify files, those changes aren't captured in the history.

File Shield was created to solve this critical gap by also listening to file system change events, ensuring every modification is backed up regardless of source - whether it's you typing, an AI assistant rewriting code, or a build tool generating files.

Technical Details

Language: TypeScript
Minimum VSCode: 1.80.0
Events:
- workspace.onDidSaveTextDocument
- workspace.createFileSystemWatcher('**/*').onDidChange
- workspace.createFileSystemWatcher('**/*').onDidCreate
Storage: VSCode Global Storage API
Dependencies:
- minimatch - Glob pattern matching for exclusions
Debouncing: 1000ms per file
Pattern Matching: Supports .gitignore syntax and glob patterns

License

MIT

Contributing

Found a bug or have a feature request? Please open an issue on GitHub.

Support

If you find this extension useful, please:

⭐ Star the repository
🐛 Report bugs
💡 Suggest features
📢 Share with others

Note: This extension runs automatically on workspace startup. No manual activation required.

File Shield

anatolii.husakovskyi