sloth-tidy: a local AI that tidies your messy folder (and lets you undo it)

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

My Downloads folder is a museum of good intentions: IMG_0509.png, final_FINAL_v3.md, a pile of WhatsApp Image 2026-09-23 at 9.12.19 PM.png, and an invoice I keep meaning to deal with. Sorting it by hand is exactly the kind of chore I put off forever.

sloth-tidy is a lazy, local, undoable file tidier. You point it at a folder. A small open-weight model running on my own laptop reads each file's name and the start of its contents, decides what the file is, gives it a clean name, and files it away:

Receipts/    invoice-7qecmbeg-0001.pdf, payment-receipt-0612-9321.pdf
Documents/   daily-notes.docx
Images/      whatsapp-image-2026-09-23.png, ...

The only effort left for me is one click to approve. It has a small browser UI (python3 sloth_tidy.py gui) and a CLI, including a watch mode that tidies a folder in the background every few minutes.

Because a lazy tool must not be a reckless one, it is built to be safe to be lazy with:

• Dry run first. It shows the plan, grouped by category, and nothing moves until I say so. I can untick anything I disagree with.
• Undo. Every run is logged, and one click puts every file back where it was.
• It never overwrites. Name collisions get -1, -2 suffixes.
• It is careful with a real Downloads folder. A file that is open in another program is skipped and reported (everything else still moves and stays undoable), and unfinished downloads (.crdownload, .part) and system files like desktop.ini are left alone.

Demo

The video shows the whole flow on a real folder of 13 files: a no-AI dry run, the real run with the model, reviewing the plan, moving the files, and Undo.

Code

Hasalawa / sloth-tidy

A lazy, local, undoable file tidier.

A small open-weight model running in Ollama reads each file's name and a short snippet,
picks a category and a clean file name, and moves it. Nothing leaves your machine.

_{▶ Watch the 2-minute demo}

Built for the DEV Hacktoberfest Open-Source AI Challenge, Week 3: Slow and Steady Started and finished inside the challenge window (Oct 19 to Oct 25, 2026).

---

✨ Why you might like it

🧠 Reads, not just sorts	A rule engine only sees the extension. The model also sees the file's name and, for text files, its first lines, so an invoice can land in Receipts/ with a readable name.
🔒 Private by construction	Files are read by a model on your own machine. No API key, no upload, works offline.
👀 Look before it moves	Dry run by default. You get a plan grouped by category and can

…

View on GitHub

One Python file, standard library only, plus tests and GitHub Actions CI. No pip install, no API key, no account.

How I Built It

The open pieces that make it work:

• Ollama for local inference, with llama3.2:3b, an open-weight model, as the default. The --model flag (or the dropdown in the UI) swaps in any model you have pulled.
• Ollama's structured outputs: the request carries a JSON schema where category is an enum, so the model has to pick from my list and return {category, new_name}. That is what makes a 3B model reliable enough for this job.

The pipeline is deliberately boring:

1. For each file, send the name, size and the first 600 characters (text-like files only) to Ollama's /api/chat.
2. Treat the model as an untrusted advisor. The suggested name is slugified (a model answering ../../evil produces a file called evil), unknown categories are thrown away, and the browser UI's server re-validates every move it is asked to make.
3. If Ollama is down, or the model returns junk for one file, that file falls back to simple extension rules. The tool degrades instead of breaking.
4. Every real run is written to a log inside the folder, which is what makes Undo possible.

I tested the logic and the local web UI's API against a fake Ollama server (20 tests, including path traversal, name collisions, garbage model output, Ollama being offline, locked files, unfinished downloads, Windows reserved names and tampered requests), so CI needs no GPU and no model. I also drove the UI in a real browser end to end.

I built this with the help of an AI assistant (Claude) for coding, testing and the demo editing, which the challenge allows.

Why Does Open Innovation Matter?

A file tidier is about the most privacy-sensitive thing you can point an AI at. It reads receipts, scans, notes and screenshots. With a closed API, "tidy my Downloads" means uploading my Downloads. With a local open-weight model, the path is: disk, my own RAM, disk. The files never leave the machine, and it works with the network unplugged.

• Privacy by construction, not by policy. There is no server I have to trust.
• No per-file cost. A cleanup touches many files, and a watch loop touches them again and again. Per-token pricing punishes exactly the lazy, repetitive automation this week's theme asks for. Locally, the cost is electricity.
• I control the behaviour. The categories and the prompt are a few lines at the top of one file, and --model swaps the model. A bigger model for a big cleanup, a tiny one for a nightly watch. Nobody can deprecate or change it under me.
• Structured output is a feature of the runtime I control, and it is what made a small model dependable enough to ship.

Where open did not win: being honest about the trade-off. The 3B model named my camera photos fairly generically (image-from-snippet.png, image-from-screenshot.png) because it only sees a filename and no pixels, and it took roughly a minute on my laptop's CPU for 13 files. A large hosted model would probably name things better and faster. For this job I accept that: the review step catches the weak names, and nothing private is uploaded.

The Lazy Payoff

On a real folder from my Downloads (13 files: a document, 10 images, an invoice and a receipt):

• The no-AI dry run was instant. The model run took about a minute on my laptop CPU, and I did something else while it ran.
• The model put the invoice and the receipt in Receipts/ with clean names. The 10 images went to Images/ with names that were readable but not always descriptive.
• Total effort from me: paste a path, click Take a look, click Move. Undo restored all 13 files exactly, both times I tried it.

I have not measured how much time this saves over weeks, so I will not pretend to. The point is that the chore now costs me two clicks instead of an afternoon I would never schedule.