Skip to content
Back to search

desk-sorter

SkillWorks with Claude CodeGitHub

Tidy the images and videos in messy Mac folders (Downloads, Desktop, screenshots, old exports) by sight. Builds a local page that shows every picture and video as one long list of thumbnails; the person sorts them into their own buckets with number keys; then Claude proposes where each bucket goes and moves files only after the person's yes, with a log that undoes it. Use when someone wants to clean up, sort, organize or declutter pictures, screenshots or videos on their Mac.

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/frederikeff--desk-sorter/badge.svg)](/listings/frederikeff--desk-sorter)

HTML

<a href="/listings/frederikeff--desk-sorter"><img src="/api/listings/frederikeff--desk-sorter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 73 lines
  1. ---
  2. name: desk-sorter
  3. description: Tidy the images and videos in messy Mac folders (Downloads, Desktop, screenshots, old exports) by sight. Builds a local page that shows every picture and video as one long list of thumbnails; the person sorts them into their own buckets with number keys; then Claude proposes where each bucket goes and moves files only after the person's yes, with a log that undoes it. Use when someone wants to clean up, sort, organize or declutter pictures, screenshots or videos on their Mac.
  4. ---
  5. # Desk Sorter
  6. The person decides; you do the work around it. They look at their pictures and sort them on a page. You make the page, read what they chose, and move files only when they say yes.
  7. Everything runs on their Mac. Pictures, thumbnails and file names never go to an outside service. Do not open or describe their pictures unless they ask: these are private files.
  8. The scripts are in this skill's folder, the folder this file is in. Run them from there. They need macOS (they use `sips` and `qlmanage`) and `python3`; if `python3` is missing, macOS offers to install the Command Line Tools.
  9. ## 1. Which folders, and how big
  10. Ask which folders to sort (Downloads and Desktop are the usual ones). Measure before anything else and tell them:
  11. ```
  12. du -sh ~/Downloads
  13. find ~/Downloads -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.heic' -o -iname '*.mov' -o -iname '*.mp4' \) | wc -l
  14. ```
  15. Ask for their buckets: brands, projects, clients, "Personal", "Delete?", "Not sure". Their own words work best. They can add more on the page later.
  16. ## 2. Make the sheet (reads only)
  17. ```
  18. python3 make_sheet.py <sheet> <folder> [<folder> ...] [--skip <folder>] --buckets "A,B,Delete?,Not sure"
  19. ```
  20. `<sheet>` is a short name such as `downloads`. This writes `data/<sheet>/` (the list and 320 px thumbnails) and moves nothing. Report what it prints: images, videos, and how many live only in iCloud. Those get no thumbnail, because making one would download them. To see them, she Control-clicks the folder in Finder and chooses Keep Downloaded (it downloads everything inside: give the folder's size and the free disk space first), then you run `make_sheet.py` again. If Desktop and Documents sync to iCloud, a later delete there syncs to every device too: say so.
  21. ## 3. Open the page
  22. Pick a free port (check that `lsof -ti tcp:8791` prints nothing), then start the server in the background:
  23. ```
  24. python3 server.py <sheet> 8791
  25. ```
  26. Give them http://127.0.0.1:8791 and the keys: click to select, Shift-click for a range, "select folder" for a whole folder, 1–9 and 0 to put the selection in a bucket, X to clear, N to give the selection a name or topic (it becomes a subfolder later), Space for a full preview. It saves by itself, so they can stop and come back.
  27. Then wait. They may sort for hours. Don't ask whether they are done.
  28. ## 4. Propose the moves (still reads only)
  29. When they say they are done, or want to move what they have so far:
  30. ```
  31. python3 apply.py <sheet>
  32. ```
  33. This writes `data/<sheet>/plan.json` and prints, for each bucket, how many files, how big, and where they would go (first suggestion: `~/Sorted/<bucket>`). Show them that list in plain words and ask where each bucket should go. Edit `plan.json` to match their answers:
  34. - a folder path: move there;
  35. - `""`: leave those files where they are;
  36. - `"TRASH"`: to the Trash. Write this only for a bucket they have named for the Trash in this conversation.
  37. ## 5. Move, only at their yes
  38. Show the final plan once more. Only after a clear yes:
  39. ```
  40. python3 apply.py <sheet> --go
  41. ```
  42. It never overwrites (a taken name gets " (2)"), logs every move in `data/<sheet>/moves-<time>.tsv`, and prints the undo command. Tell them the counts and where the log is. Never use `rm`. Never empty the Trash.
  43. To undo: `python3 apply.py <sheet> --undo <log file>`. Files sent to the Trash come back with Finder's "Put Back".
  44. ## 6. Close
  45. Stop the server by its port: `lsof -ti tcp:8791 | xargs kill`. The `data/` folder holds their thumbnails and file paths. It stays on their Mac and should never go into git. They may delete it when they no longer need the sheet.
README.md · README · 93 lines
  1. # Desk Sorter
  2. Sort thousands of pictures and videos on your Mac by looking at them, not by opening them one by one.
  3. It shows every image and video in the folders you pick as one long page of thumbnails. You select a few, or a whole folder, press a number key, and they're in a bucket: a brand, a project, "Personal", "Delete?". When you're done, it shows where each bucket would go and moves the files only when you say so. Every move is logged and can be undone.
  4. It runs on your Mac only. Nothing is uploaded, and no AI looks at your pictures.
  5. I built it with Claude Code for my own Downloads folder: 4,784 images and videos in 94 folders, which no app sorted the way I think about my work. I sorted 3,500 of them in one evening.
  6. ## What you need
  7. - A Mac. It uses the Mac's own `sips` and `qlmanage` for thumbnails.
  8. - `python3`. Type it in Terminal. If it's missing, macOS offers to install it (the Command Line Tools).
  9. - Nothing else: no packages, no account, no internet.
  10. ## Use it with Claude Code (easiest)
  11. Install it as a skill:
  12. ```
  13. git clone https://github.com/frederikeff/desk-sorter ~/.claude/skills/desk-sorter
  14. ```
  15. Then tell Claude Code: "sort the pictures in my Downloads". Claude measures the folder, asks for your buckets, opens the page, and waits while you sort. Afterwards it shows you the plan and moves files only after your yes.
  16. ## Use it by hand
  17. ```
  18. cd desk-sorter
  19. # 1. Make the sheet. This only reads; nothing moves.
  20. python3 make_sheet.py downloads ~/Downloads --buckets "Work,Personal,Content,Delete?,Not sure"
  21. # 2. Sort on the page: http://127.0.0.1:8791
  22. python3 server.py downloads
  23. # 3. See the plan. This writes data/downloads/plan.json; nothing moves.
  24. python3 apply.py downloads
  25. # 4. Change the targets in plan.json if you like, then move.
  26. python3 apply.py downloads --go
  27. # Changed your mind?
  28. python3 apply.py downloads --undo moves-<time>.tsv
  29. ```
  30. ### On the page
  31. | Key | What it does |
  32. |---|---|
  33. | Click, Shift-click | Select, select a range |
  34. | "select folder" | Select all of a folder |
  35. | 1–9, 0 | Put the selection in that bucket |
  36. | X | Take the selection out of its bucket |
  37. | N | Name the selection (becomes a subfolder when moving) |
  38. | Space, double-click | Full preview; arrows move, Esc closes |
  39. | "+ bucket" | Add a bucket |
  40. It saves as you go. Close the page, stop the server, come back tomorrow: your choices are still there.
  41. ### In plan.json
  42. ```json
  43. {
  44. "use_names_as_subfolders": true,
  45. "buckets": {
  46. "Work": "~/Sorted/Work",
  47. "Not sure": "",
  48. "Delete?": "TRASH"
  49. }
  50. }
  51. ```
  52. A folder path means "move there". `""` means "leave them where they are". `"TRASH"` puts them in the Trash, where Finder's "Put Back" still works. The first plan suggests `~/Sorted/<bucket>` for every bucket and never suggests the Trash: you write `TRASH` yourself.
  53. ## Safe by design
  54. - `make_sheet.py` and the page only read your files. Only `apply.py --go` moves anything.
  55. - It never overwrites a file. A name that is taken gets " (2)".
  56. - It never deletes. The Trash is as far as it goes, and only for buckets you mark.
  57. - The page listens on 127.0.0.1, so no other computer can reach it, and it only serves files that are in your sheet.
  58. - Your thumbnails and file list stay in `data/`, which is ignored by git.
  59. ## Good to know
  60. - **iCloud:** files that live only in iCloud ("Optimize Mac Storage") show "only in iCloud" instead of a thumbnail, because making one would download them. To see them, Control-click the folder in Finder and choose **Keep Downloaded** (it downloads everything inside, so check the folder's size and your free space first), then run `make_sheet.py` again. Moving files on the same disk is a rename, so files only in iCloud can be moved without downloading them. If your Desktop and Documents sync to iCloud, whatever you move or trash there changes on your other devices too.
  61. - **Big folders:** making the sheet for 4,784 files took under two minutes on my Mac. Thumbnails are reused when you run it again.
  62. - **Only images and videos.** PDFs, zips and installers are a job for another day.
  63. ## License
  64. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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