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
Markdown
[](/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
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
- ---
- name: safe-storage-cleanup
- 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".
- ---
- # Safe storage cleanup
- 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.**
- Data loss is the one failure you cannot undo. When in doubt: stop, list, ask.
- ## 1. Start of every session
- 1. Agree on an **audit folder** (e.g. `~/StorageAudit`). All scripts, CSVs, logs and notes go there, never onto the drives being cleaned.
- 2. If a handoff file exists there (highest-numbered `NN_handoff_YYYY-MM-DD.md`), read it first.
- 3. Ask which drives are busy (a backup running, the user deleting by hand) and avoid heavy I/O on them.
- 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).
- ## 2. Hard rules (never break)
- - **Read-only by default.** Every pass starts as a report: a CSV of candidates with sizes and evidence.
- - **Never recommend deleting.** List candidates with evidence; the user decides.
- - **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.
- - **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.
- - **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.
- - **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.
- - NAS and network deletes often skip the recycle bin. Treat them as permanent and remind the user.
- - Never echo credentials (mapped-drive passwords, NAS logins) into chat, logs or scripts.
- ## 3. The safe move / delete protocol
- Every destructive step goes **copy → SHA-256 verify → delete**, per file:
- 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.
- 2. Hash target and source; delete the source only on a match.
- 3. For "remove because a copy exists elsewhere": **live-hash both files right before deleting.** Never delete on a cached hash alone.
- 4. Log every file to a numbered CSV: what, where, size, result (`REMOVED`, `MOVED_OK`, `ALREADY`, `KEPT_<reason>`, `MISMATCH`).
- 5. Anything that fails a check is **kept** and logged, never forced.
- 6. Remove folders only once they are empty. Sync clients (Dropbox, OneDrive) may hold empty shells: report them, don't fight them.
- 7. Scripts are **resumable**: a re-run only acts on what is still pending.
- 8. Always do a dry run first and show the user the totals before the real run.
- ## 4. Duplicate detection method (`scripts/find_dupes.py`)
- - Index path, size and mtime. On Windows, use the `\\?\` prefix so paths over 260 characters work. Unreadable files are logged and skipped.
- - **Size prefilter:** hash only files whose size collides with another file. This cuts millions of hashes down to a manageable number.
- - SHA-256 the collisions and group identical files.
- - 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.
- - **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.
- - If you keep a hash cache, trust an entry only if the file still exists with the same size and mtime.
- ## 5. Junk categories (propose; never auto-delete)
- Inside old PC backups / drive dumps these are usually regenerable:
- - `Windows/`, `Program Files*/`, `ProgramData/`, `$Windows.~BT`, `$Recycle.Bin`
- - browser and app caches (`cache`, `cache2`, `Code Cache`, `GPUCache`)
- - `AppData/Local/Temp`, `*.tmp`
- - `pagefile.sys`, `hiberfil.sys`, Outlook `.ost` files (the mail stays on the server; `.pst` is NOT junk)
- - `.next/cache`, `node_modules`
- - Lightroom `*Previews.lrdata` / `*Smart Previews.lrdata`. Keep the `.lrcat` catalog: it holds the edits.
- Per-file junk: `Thumbs.db`, `desktop.ini`, `.DS_Store`, `~$*`, zero-byte files.
- Exceptions to flag: some apps keep real data in `.tmp` files (e.g. unfinished meeting recordings), so check before calling a `.tmp` junk.
- Present junk **by category with totals**. The user picks the categories.
- ## 6. Keeping an add-only backup in step after a reorganization (`scripts/backup_parity.py`)
- After the source is reorganized, an add-only backup would copy everything again under the new paths and double its size. Instead:
- 1. Index the source and the backup.
- 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.
- 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.
- 4. Report what is left: files only on the backup (never touched automatically) and new source files the next backup run will copy.
- 5. Then duplicates on the backup can be removed with the live-hash rule (`scripts/verified_remove.py`).
- ## 7. Scripts (Python 3 stdlib only, dry run by default)
- | Script | Does | Writes to data drives? |
- |---|---|---|
- | `find_dupes.py ROOT... --out dupes.csv [--protect DIR] [--min-size N]` | index + size prefilter + SHA-256, suggests KEEP/REMOVE per group | No |
- | `verified_remove.py plan.csv [--run]` | plan columns `Remove,Keep`: live-hash both, remove only on match | Yes, with `--run` |
- | `safe_move.py plan.csv [--run]` | plan columns `Source,Target`: copy → verify → delete, never overwrite | Yes, with `--run` |
- | `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` |
- 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`.
- Run long jobs in the background with a status file; number every output (`NN_name.csv`); never overwrite an older numbered result.
- ## 8. Reporting
- - Lead with the answer: safe / not safe, GiB freed / possible.
- - Separate **freed** vs **ready to free** vs **possible (user decides)**.
- - Point to the CSV holding the evidence and name exact paths.
- - 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
- # safe-storage-cleanup: a Claude Code skill
- 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.
- **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.
- ## Install
- 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's inside
- - `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).
- - `scripts/`: Python 3 standard library only, no installs needed. Every script that changes anything is a **dry run unless you pass `--run`**.
- | Script | Purpose |
- |---|---|
- | `find_dupes.py` | Read-only. Index → size prefilter → SHA-256 on collisions → CSV of duplicate groups with suggested KEEP/REMOVE (`--protect` folders always win) |
- | `verified_remove.py` | Removes `Remove,Keep` pairs only after a live SHA-256 of both copies matches |
- | `safe_move.py` | Copy → verify → delete moves; never overwrites |
- | `backup_parity.py` | Renames files on the backup to match a reorganized source (server-side on a NAS: no re-copy) |
- The scripts can also be used by hand without Claude; run any of them with `--help`.
- ## Limits / honesty
- - Duplicates are matched by content (SHA-256); `backup_parity.py` matches by name + size + mtime and skips anything ambiguous.
- - NAS deletes often bypass the recycle bin. Check that the copy you keep is itself backed up before removing the other one.
- - Test on a small folder first. No warranty: it's your data, so read the dry-run output.
- ## License
- MIT. See `LICENSE`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.