Monitor Backup Before Edit

Creates timestamped backup copies of files before Claude modifies them, providing a safety net for recovering previous versions.

When to Use This Hook

Attach this hook when you need to:

• Preserve original file contents before Claude makes changes for easy rollback
• Create an audit trail of file states during complex multi-file refactoring sessions
• Provide a safety net in projects where git history alone is insufficient for recovery

Consider alternatives when:

• Your project uses git and you are comfortable recovering from git checkout or git stash
• Storage space is limited and creating backup copies of every edited file is impractical

Quick Start

Configuration

Copy
name: monitor-backup-before-edit
type: hook
trigger: PreToolUse
category: pre-tool

Example Trigger

Copy
# Hook triggers before Claude edits a file
claude> Edit src/config/database.ts
# Backup created before the edit proceeds

Example Output

Backup created: src/config/database.ts.backup.1710523847
Original file preserved. Edit proceeding...

Core Concepts

Backup Strategy Overview

Aspect	Details
Trigger Point	PreToolUse - runs before the edit happens
Naming Convention	{filename}.backup.{unix_timestamp}
Scope	Only backs up files that already exist
Storage	Same directory as the original file
Error Handling	Silently continues if backup fails

Backup Workflow

Edit Requested
      |
  File Exists?
   /        \
  No        Yes
  |          |
Skip      Copy File
           |
     Add Timestamp
     Suffix
           |
     backup.1710523847
           |
     Allow Edit
     to Proceed

Configuration

Parameter	Type	Default	Description
matcher	string	"Edit"	Tool operation that triggers backup creation
backup_dir	string	same directory	Directory to store backup files
max_backups	number	unlimited	Maximum backups per file before oldest is deleted
timestamp_format	string	"%s" (epoch)	Timestamp format for backup filenames
exclude_patterns	string[]	[]	File patterns to skip backing up

Best Practices

1. Set a Backup Retention Limit - Without max_backups, long sessions create dozens of backup files per edited file. Set a limit of 3-5 backups per file and auto-delete the oldest to prevent directory clutter.

2. Use a Dedicated Backup Directory - Store backups in .claude/backups/ rather than alongside source files. This keeps the working directory clean and makes cleanup easy without risking deletion of source files.

3. Add Backups to .gitignore - Ensure .backup.* patterns are in .gitignore so backup files are never accidentally committed. This prevents repository bloat and keeps git history clean.

4. Extend to Write and MultiEdit - The default hook only backs up on Edit. Add matchers for Write (if overwriting) and MultiEdit to cover all file modification scenarios.

5. Clean Up After Sessions - Add a session-end hook or manual step to delete all backup files once you are satisfied with the changes. Stale backups from previous sessions have diminishing value.

Common Issues

1. Disk Space Exhaustion - Backing up large files repeatedly fills disk space quickly. Exclude binary files and large generated assets from backup, or set a per-file size limit.

2. Permission Errors on Read-Only Files - If the source file is readable but its directory is not writable, the backup copy fails. The error suppression handles this, but consider logging a warning.

3. Backup of Backup Files - If a subsequent edit targets a .backup file (unlikely but possible), the hook creates a backup of the backup. Add an exclusion pattern for *.backup.* to prevent this recursion.