Skip to content
Back to search

safe-storage-cleanup

Safe, evidence-first cleanup of home or NAS storage. Use for de-duplicating files across drives, merging duplicate libraries (photos, ebooks, music), removing junk from old PC backups, moving data between drives, and keeping an add-only backup in step after a reorganization, all without losing data. Triggers include "find duplicates", "dedupe my drives", "free up space on my NAS", "clean up old backups", "merge these folders", "my backup will duplicate everything after I reorganized".

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/strategenixsolutions-ux--safe-storage-cleanup/badge.svg)](/listings/strategenixsolutions-ux--safe-storage-cleanup)

HTML

<a href="/listings/strategenixsolutions-ux--safe-storage-cleanup"><img src="/api/listings/strategenixsolutions-ux--safe-storage-cleanup/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy the `safe-storage-cleanup` folder into your Claude Code skills folder: - Windows: `%USERPROFILE%\.claude\skills\safe-storage-cleanup\` - macOS / Linux: `~/.claude/skills/safe-storage-cleanup/`

Then ask Claude Code things like *"find duplicates between D:\Photos and my NAS photo backup"* or *"I reorganized my data drive, don't let my backup duplicate everything"*.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 82 lines
  1. ---
  2. name: safe-storage-cleanup
  3. description: Safe, evidence-first cleanup of home or NAS storage. Use for de-duplicating files across drives, merging duplicate libraries (photos, ebooks, music), removing junk from old PC backups, moving data between drives, and keeping an add-only backup in step after a reorganization, all without losing data. Triggers include "find duplicates", "dedupe my drives", "free up space on my NAS", "clean up old backups", "merge these folders", "my backup will duplicate everything after I reorganized".
  4. ---
  5. # Safe storage cleanup
  6. The user owns the data and makes every keep/delete decision. Your job: **find, prove, propose, and only when the user names the exact action, execute safely.**
  7. Data loss is the one failure you cannot undo. When in doubt: stop, list, ask.
  8. ## 1. Start of every session
  9. 1. Agree on an **audit folder** (e.g. `~/StorageAudit`). All scripts, CSVs, logs and notes go there, never onto the drives being cleaned.
  10. 2. If a handoff file exists there (highest-numbered `NN_handoff_YYYY-MM-DD.md`), read it first.
  11. 3. Ask which drives are busy (a backup running, the user deleting by hand) and avoid heavy I/O on them.
  12. 4. Ask which folders are **protected**: sources of truth that must never be the copy that gets removed (e.g. a scanned family-photo collection).
  13. ## 2. Hard rules (never break)
  14. - **Read-only by default.** Every pass starts as a report: a CSV of candidates with sizes and evidence.
  15. - **Never recommend deleting.** List candidates with evidence; the user decides.
  16. - **Only do the move/delete the user names**, with the exact folders and exact scope. Approval for one action does not carry over to the next.
  17. - **Never change permissions or attributes** to get past a locked, read-only, access-denied or antivirus-blocked file (no attrib, icacls, takeown, chmod, chown). Mark it KEPT and report it.
  18. - **Backups are add-only.** Never use mirror/purge modes (`robocopy /MIR` or `/PURGE`, `rsync --delete`). A mistake on the source must never propagate to the backup.
  19. - **Before removing a duplicate, check where the backup of the copy being kept lives.** If the copy being removed is the only second copy, say so before acting.
  20. - NAS and network deletes often skip the recycle bin. Treat them as permanent and remind the user.
  21. - Never echo credentials (mapped-drive passwords, NAS logins) into chat, logs or scripts.
  22. ## 3. The safe move / delete protocol
  23. Every destructive step goes **copy → SHA-256 verify → delete**, per file:
  24. 1. Copy with timestamps preserved (`shutil.copy2`). **Never overwrite.** If the target exists, hash-compare it: identical = ALREADY (the source may go), different = stop and report.
  25. 2. Hash target and source; delete the source only on a match.
  26. 3. For "remove because a copy exists elsewhere": **live-hash both files right before deleting.** Never delete on a cached hash alone.
  27. 4. Log every file to a numbered CSV: what, where, size, result (`REMOVED`, `MOVED_OK`, `ALREADY`, `KEPT_<reason>`, `MISMATCH`).
  28. 5. Anything that fails a check is **kept** and logged, never forced.
  29. 6. Remove folders only once they are empty. Sync clients (Dropbox, OneDrive) may hold empty shells: report them, don't fight them.
  30. 7. Scripts are **resumable**: a re-run only acts on what is still pending.
  31. 8. Always do a dry run first and show the user the totals before the real run.
  32. ## 4. Duplicate detection method (`scripts/find_dupes.py`)
  33. - Index path, size and mtime. On Windows, use the `\\?\` prefix so paths over 260 characters work. Unreadable files are logged and skipped.
  34. - **Size prefilter:** hash only files whose size collides with another file. This cuts millions of hashes down to a manageable number.
  35. - SHA-256 the collisions and group identical files.
  36. - Keep-rule suggestions (the user confirms): a protected folder always wins, then the cleanest name (no ` (1)`, ` - Copy`, `copy of`), then the copy in the folder the user calls "home", then the shortest path.
  37. - **Redundant folders:** look for top-most folders whose every file has a copy outside them, so whole trees can go while one copy of everything survives.
  38. - If you keep a hash cache, trust an entry only if the file still exists with the same size and mtime.
  39. ## 5. Junk categories (propose; never auto-delete)
  40. Inside old PC backups / drive dumps these are usually regenerable:
  41. - `Windows/`, `Program Files*/`, `ProgramData/`, `$Windows.~BT`, `$Recycle.Bin`
  42. - browser and app caches (`cache`, `cache2`, `Code Cache`, `GPUCache`)
  43. - `AppData/Local/Temp`, `*.tmp`
  44. - `pagefile.sys`, `hiberfil.sys`, Outlook `.ost` files (the mail stays on the server; `.pst` is NOT junk)
  45. - `.next/cache`, `node_modules`
  46. - Lightroom `*Previews.lrdata` / `*Smart Previews.lrdata`. Keep the `.lrcat` catalog: it holds the edits.
  47. Per-file junk: `Thumbs.db`, `desktop.ini`, `.DS_Store`, `~$*`, zero-byte files.
  48. Exceptions to flag: some apps keep real data in `.tmp` files (e.g. unfinished meeting recordings), so check before calling a `.tmp` junk.
  49. Present junk **by category with totals**. The user picks the categories.
  50. ## 6. Keeping an add-only backup in step after a reorganization (`scripts/backup_parity.py`)
  51. After the source is reorganized, an add-only backup would copy everything again under the new paths and double its size. Instead:
  52. 1. Index the source and the backup.
  53. 2. For each backup file whose path no longer exists on the source, find the source file it became: same name + size + mtime (±2 s), else a *unique* size + mtime match.
  54. 3. **Rename on the backup side** (server-side on a NAS, so no data is copied) to the new path. Never overwrite; skip ambiguous matches.
  55. 4. Report what is left: files only on the backup (never touched automatically) and new source files the next backup run will copy.
  56. 5. Then duplicates on the backup can be removed with the live-hash rule (`scripts/verified_remove.py`).
  57. ## 7. Scripts (Python 3 stdlib only, dry run by default)
  58. | Script | Does | Writes to data drives? |
  59. |---|---|---|
  60. | `find_dupes.py ROOT... --out dupes.csv [--protect DIR] [--min-size N]` | index + size prefilter + SHA-256, suggests KEEP/REMOVE per group | No |
  61. | `verified_remove.py plan.csv [--run]` | plan columns `Remove,Keep`: live-hash both, remove only on match | Yes, with `--run` |
  62. | `safe_move.py plan.csv [--run]` | plan columns `Source,Target`: copy → verify → delete, never overwrite | Yes, with `--run` |
  63. | `backup_parity.py plan SRC BACKUP --out plan.csv` then `backup_parity.py run plan.csv [--run]` | rename the backup to match the reorganized source | Yes (renames), with `--run` |
  64. Typical flow: `find_dupes.py` → the user reviews the CSV and keeps the REMOVE rows they approve → save them as `Remove,Keep` → `verified_remove.py plan.csv` (dry) → show totals → `--run`.
  65. Run long jobs in the background with a status file; number every output (`NN_name.csv`); never overwrite an older numbered result.
  66. ## 8. Reporting
  67. - Lead with the answer: safe / not safe, GiB freed / possible.
  68. - Separate **freed** vs **ready to free** vs **possible (user decides)**.
  69. - Point to the CSV holding the evidence and name exact paths.
  70. - After each meaningful step, update a dated handoff file in the audit folder (what was done, totals, open items, things on hold). On a new day, start a new numbered handoff that supersedes the old one.
README.md · README · 33 lines
  1. # safe-storage-cleanup: a Claude Code skill
  2. This skill turns Claude Code into a careful storage-cleanup assistant: de-duplication across drives, merging duplicate libraries, junk removal from old PC backups, and keeping an add-only backup in step after a reorganization.
  3. **You make every keep/delete decision.** Claude finds, proves (with SHA-256), proposes, and executes only the exact action you name. It always does a dry run first and logs every file.
  4. ## Install
  5. Copy the `safe-storage-cleanup` folder into your Claude Code skills folder:
  6. - Windows: `%USERPROFILE%\.claude\skills\safe-storage-cleanup\`
  7. - macOS / Linux: `~/.claude/skills/safe-storage-cleanup/`
  8. Then ask Claude Code things like *"find duplicates between D:\Photos and my NAS photo backup"* or *"I reorganized my data drive, don't let my backup duplicate everything"*.
  9. ## What's inside
  10. - `SKILL.md`: the rules and method Claude follows (read-only by default, live-hash before delete, copy → verify → delete, add-only backups, never force permissions).
  11. - `scripts/`: Python 3 standard library only, no installs needed. Every script that changes anything is a **dry run unless you pass `--run`**.
  12. | Script | Purpose |
  13. |---|---|
  14. | `find_dupes.py` | Read-only. Index → size prefilter → SHA-256 on collisions → CSV of duplicate groups with suggested KEEP/REMOVE (`--protect` folders always win) |
  15. | `verified_remove.py` | Removes `Remove,Keep` pairs only after a live SHA-256 of both copies matches |
  16. | `safe_move.py` | Copy → verify → delete moves; never overwrites |
  17. | `backup_parity.py` | Renames files on the backup to match a reorganized source (server-side on a NAS: no re-copy) |
  18. The scripts can also be used by hand without Claude; run any of them with `--help`.
  19. ## Limits / honesty
  20. - Duplicates are matched by content (SHA-256); `backup_parity.py` matches by name + size + mtime and skips anything ambiguous.
  21. - NAS deletes often bypass the recycle bin. Check that the copy you keep is itself backed up before removing the other one.
  22. - Test on a small folder first. No warranty: it's your data, so read the dry-run output.
  23. ## License
  24. MIT. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.