recycle-bin

Recycle Bin - File Recovery Skill

Recover accidentally deleted files from the recycle bin. Use this skill proactively when you detect that a file has been deleted and may need to be recovered.

When to Use

Use this skill when:

• A file deletion was accidental or premature
• You need to recover a file that was moved to trash
• You want to list what files are available for recovery
• The user asks about recovering deleted files

Usage

/recycle-bin list                       # List all recoverable files
/recycle-bin recover <id>               # Recover to original location
/recycle-bin recover <id> --to <path>   # Recover to different location
/recycle-bin recover <id> --force       # Overwrite if destination exists
/recycle-bin purge <id>                 # Permanently delete from trash
/recycle-bin status                     # Check if hook is installed

Instructions

Listing Recoverable Files

To see what files can be recovered:

python3 .claude/scripts/manage-recycle-bin.py list

This shows:

• Recovery ID (use this for recover/purge commands)
• Original file name
• When it was deleted
• File type
• Original path

Recovering a File

To recover a file to its original location:

python3 .claude/scripts/manage-recycle-bin.py recover <recovery_id>

To recover to a different location:

python3 .claude/scripts/manage-recycle-bin.py recover <recovery_id> --to /path/to/new/location

To overwrite an existing file:

python3 .claude/scripts/manage-recycle-bin.py recover <recovery_id> --force

Proactive Recovery

When you notice:

1. A file was deleted that shouldn't have been
2. A build/test failure references a missing file that was recently deleted
3. The user mentions a file they need that was deleted

You should:

1. List recoverable files to find the file
2. Verify it's the right file (check original path and deletion time)
3. Recover it to the appropriate location
4. Inform the user what was recovered

Checking Hook Status

To verify the recycle bin hook is active:

python3 .claude/scripts/manage-recycle-bin.py status

If not installed, suggest: /recycle-bin install

Security Guarantees

The hook NEVER allows deletion of:

1. Files in .trash/ directories - Prevents loss of recoverable files
2. Files outside CLAUDE_PROJECT_DIR - Prevents system damage

If a file cannot be safely moved to trash, deletion is BLOCKED (not allowed).

How the Hook Works

When installed, the recycle bin hook:

1. Verifies the file is inside the project directory
2. Intercepts rm, unlink, and trash commands
3. Moves files to .claude/bonfire/[plan]/.trash/
4. Creates metadata for each file (original path, deletion time, etc.)
5. Blocks the original deletion command with feedback to Claude

The hook does NOT protect files in (deletions proceed normally):

• node_modules/, .git/, __pycache__/
• dist/, build/, .next/, .nuxt/
• .venv/, venv/, .tox/, coverage/

File Locations

• Trash directory: .claude/bonfire/[plan]/.trash/
• Each file has: [recovery_id]-[filename]/content (the file) and metadata.json

Example Session

Claude: I notice the config.py file was deleted but is needed for the build.
        Let me check if it can be recovered.

> python3 .claude/scripts/manage-recycle-bin.py list

Recoverable Files
============================================
Recovery ID  Original Name  Deleted At            Type    Path
abc12345     config.py      2026-01-16T10:30:00   file    ...src/config.py
--------------------------------------------

Claude: Found it. Let me recover the config.py file.

> python3 .claude/scripts/manage-recycle-bin.py recover abc12345

FILE RECOVERED
Original: /path/to/src/config.py
Restored: /path/to/src/config.py

Claude: I've recovered src/config.py to its original location.
        The build should work now.

Dependencies

The hook requires bashlex for bash command parsing:

pip install bashlex