Itās been a while since I wanted something like this. Years, if Iām honest. Somewhere between the thirdĀ theme-final-FINAL-v2.zipĀ from a client and the fortieth invoice calledĀ 10228315888.pdf, my Downloads folder stopped being a folder and became the place files go to be forgotten.
It always goes the same way. During the week Iām heads-down on client work, and things quietly pile up: a logo from one client, a contract from another, a screenshot of a bug, a WhatsApp voice note, a zip of a theme āwith just a few small changesā. Nothing gets filed, because filing is never urgent.
Then the weekend arrives. I finally have a quiet hour and a coffee, so I open Downloads to tidy up my laptop⦠and close it again.Ā 3,110 files.Ā 860 PDFs, 1,300 images, 353 zips, and names likeĀ IMG_4821.heicĀ andĀ invoice (3) (1).pdf. That isnāt a tidy-up, itās an archaeological dig.
Every clean-up app I tried sorted things by file type, which just turns one mess into twelve smaller ones. So I built a free Mac app for my weekend clean-up instead. It sorts files byĀ what is actually inside them, renames the meaningless ones and lets me undo the whole thing in one click if I donāt like the result. Now the weekend tidy-up takes about as long as the coffee.
It is calledĀ Downloads Sorter. It is open source, it runs entirely on your Mac, and you can grab it fromĀ GitHub.
Why sorting by file type doesnāt work
A folder called āPDFsā with 860 files in it is not organised. What I actually want isĀ invoices here, bank statements there, contracts somewhere else, and the same for photos: the wedding pictures together, the screenshots out of the way, the logos I downloaded for client sites in one place.
That means the app has to look inside each file, the way you would if you opened it. A photo of a plate of pasta and a photo of a logo are bothĀ .pngĀ files. A gas bill and a bank statement are both PDFs. File types donāt tell them apart. The contents do.
What Downloads Sorter does

- It looks inside photos:Ā Appleās on-device Vision framework classifies each image and spots faces and on-screen text. Photos go into folders like People & selfies, Food & drinks, Nature & outdoors, Interiors & spaces, Pets & animals, Events & celebrations and Sport & hobbies.
- It reads PDFs:Ā invoices, bank statements, contracts, tax documents and boarding passes are recognised from the text inside them, in English and Romanian. A PDF that says āfacturÄā and ātotal de platÄā goes to Invoices & receipts, whatever the file name.
- It separates screenshots and graphics:Ā screen captures, logos and transparent web graphics stop cluttering your photo folders.
- It sorts videos by whatās in them:Ā clips where a face fills the frame becomeĀ Talking head, the rest becomeĀ B-roll, and screen recordings get their own folder.
- It renames what needs renaming:Ā
IMG_5020.heicĀ becomesĀGuitar 2026-08-08.heic. Files with real names keep them. - It catches the clutter:Ā byte-identical duplicates and 0-byte failed downloads go to their own folders, so you can deal with them in one go.
How it works under the hood
A tiny Swift helper does the looking
The analysis runs in a small Swift program that uses 3 Apple frameworks every Mac already has:Ā VisionĀ for image labels (over 1,300 of them), face detection and text recognition,Ā PDFKitĀ for the text inside PDFs, andĀ AVFoundationĀ for video frames and audio length. It uses all but 2 of your CPU cores. On my Mac it got through 249 mixed files in about 13 seconds, and results are cached, so a second scan only looks at new files.
Everything else is a small Python server with no dependencies and a plain HTML interface. No npm, no pip, no build step.
Rules decide the folder
Vision returns labels such asĀ food,Ā bedroomĀ orĀ receiptĀ with a confidence score. The sorter weights those labels per folder and picks the strongest match. Faces count towards People & selfies, and a lot of on-screen text pushes an image towards Screenshots or Paper & receipts. PDFs are matched against keyword lists, and the folder with the most hits wins.
Only meaningless names get changed
I didnāt want an app that renamesĀ Brand guidelines final.pdfĀ to something clever. It only renames camera-roll names, WhatsApp and Facebook exports, UUIDs, hashes and plain numbers. The new name uses the most specific thing Vision saw plus the date the photo was taken:
| Before | After |
|---|---|
| IMG_2917.HEIC | Building & cityscape 2021-09-18.HEIC |
| 20230808_103547.jpg | Selfie 2023-08-08.jpg |
| WhatsApp Image 2022-08-04 at 1.33.03 PM.jpeg | Wine & basket 2022-08-04.jpeg |
| 2a0f7ff6-d6d0-4e0b-aaef-66bc206c3797.jpeg | Sofa 2025-07-06.jpeg |
| Brand guidelines final.pdf | Brand guidelines final.pdf (kept) |

Built so you can trust it with your files
An app that moves 3,000 files around needs to earn some trust. These were my non-negotiables:
- Preview first:Ā every scan is just a plan. You see each folder, its count and its files before anything moves, and you can untick or re-route any file.
- It never deletes:Ā it only moves and renames. Even duplicates and empty files are moved to folders, not removed.
- One-click undo:Ā every sort is logged. Undo puts each file back in its original place under its original name and removes the folders it created. I tested it by sorting a copy of 249 of my real files and undoing it: every name came back exactly.
- It leaves in-progress downloads alone:Ā partial files and anything modified in the last 2 minutes are skipped.
- It is private:Ā nothing is uploaded, there is no account and no API key. The local server only listens on your own machine and needs a random token on every launch, so another web page canāt trigger it.

Your own folders, in your own words
The built-in folders cover most of a typical Downloads folder, but everyone has their own projects. In Settings you can add a folder plus a few keywords, and a file goes there when its name, what is in the picture or the text inside it matches.
When I tested aĀ WeddingĀ folder with the keywordsĀ wedding, nunta, invitati, it caught the wedding photos (Vision recognised the scene), some AI-generated bouquet ideas (from their file names) and the guest-list spreadsheets (āInvitati Nuntaā). 3 file types, 1 folder, zero manual dragging.

How to try it
You need a Mac with Python 3 and Appleās free Command Line Tools (most developers already have both).
- Clone the repository:
git clone https://github.com/costibotez/downloads-cleanup.git cd downloads-cleanup - Double-clickĀ Sort Downloads.command, or runĀ
./make-app.shĀ to build a properĀ Downloads Sorter.appĀ for your Dock. - ClickĀ AllowĀ when macOS asks for access to your Downloads folder.
- PressĀ Look at my files, check the preview, then pressĀ Sort.
The first scan of a few thousand files takes a minute or 2. You can point it at any folder, not just Downloads.
What I learned building it
- Vision labels come in families:Ā a golf ball is taggedĀ
golf, but alsoĀsportĀ andĀrecreation. The parent labels are useful for picking a folder and useless for naming a file, so the sorter keeps them for one job and ignores them for the other. - File names lie, contents donāt:Ā half of my invoices had numeric names. The text inside them was the only reliable signal.
- Safety features are the product:Ā the clever classification is the fun part, but the preview and the undo are what make you actually press the button.
- It came together fast:Ā I built the first version with Claude Code in a single afternoon session, including testing it against a copy of my real files.
Whatās next
- Move to TrashĀ for the Duplicates and Empty files folders, using the normal recoverable macOS Trash
- Watch modeĀ that files new downloads as they land
- Smarter document names, soĀ
10228315888.pdfĀ becomesĀInvoice ā Engie ā 2023-05-22.pdf
Conclusion
Most tidy-up tools treat files as extensions. Once you let the computer look inside them, the way you would, a 3,000-file Downloads folder becomes a few dozen folders that make sense, with names you can actually search for. And because it previews first, never deletes and can undo everything, it is safe to point at the folder you have been avoiding for years.
These days my weekend clean-up goes like this: open the app, press Sort, glance at the preview, done. The client files still pile up all week. Iāve just stopped dreading Saturday morning.
Downloads Sorter is free and open source on GitHub. If it saves you an afternoon, a star on the repo is always appreciated.
Need a small tool like this built for your own workflow, whether that is a WordPress plugin, an internal app or something that automates the boring parts of your business?Ā Get in touchĀ and we can talk it through. The most relevant starting points are usuallyĀ custom plugin developmentĀ andĀ SaaS and app development.





