File-Tidier: My Folders Are a Crime Scene. So I Built a Tool to Clean Up the Mess.

Hiteshi Kukreja — Sat, 24 Oct 2026 16:12:37 +0000

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

What I Built

I like keeping my files and folders organised. I want to open my Downloads folder and know where things are. I want files to have names that tell me what's inside them, instead of document.pdf, final_v2.txt or IMG_001.jpg.

The problem is that keeping everything tidy is easy only until new files start arriving.

A PDF for a project. A receipt I might need later. Notes from something I'm learning. A document downloaded in a hurry and forgotten five minutes later. The Downloads folder grows, files pile up, and the organisation I worked to maintain slowly disappears.

And then comes the worst part: you urgently need a file, but you don't know which document contains the information you're looking for. You start opening files one by one, trying to work out what each one is. Sometimes the file has the information you need, but its name tells you absolutely nothing.

I could organise everything manually. I just don't want another small, repetitive task taking time away from the work I actually want to do.

So I built File-Tidier, a local AI file organiser powered by Gemma 3 4B through Ollama.

It reads supported file content, suggests a meaningful filename and a suitable folder, and helps organise files into categories such as Study, Personal, Receipts, Travel, Photos and Work. When there's nothing it can read, or it can't make sense of a file, it goes to Needs-Review instead. You can also archive anything older than a threshold you choose, such as six months.

The idea is simple: spend less time organising your files, and less time searching for them later.

A few real results from my tests:

bill_final.txt became Receipts/rent_receipt_may_2026.txt
flight_ticket.pdf was really a restaurant bill, so it became Receipts/restaurant_bill_example.pdf
A blank image went to Needs-Review/IMG_001.jpg with its name untouched, because the tool couldn't honestly say what it was

Demo

Main demo:

Watcher demo (lazy mode):

Code

Kuki-09 / file-tidier

File-Tidier

A local AI file organizer that understands file contents, gives files meaningful names and sorts them without taking control away from you

Demo: Main Demo · Watcher Demo · Evaluation: eval/EVAL.md

File-Tidier uses Gemma 3 4B through Ollama to organize messy folders on your own computer. Instead of relying only on filenames, it reads supported documents and images, proposes descriptive names and sorts files into Study, Personal, Receipts, Travel, Photos, Work, or Needs-Review.

It also supports optional age-based archiving: choose an age threshold, such as six months and older files can be moved into Archive/ while preserving their category folders.

A generic bill_final.txt can become Receipts/rent_receipt_may_2026.txt and flight_ticket.pdf, which was really a restaurant bill, became Receipts/restaurant_bill_example.pdf. A misleading filename does not have to dictate where a file goes. If a file cannot be read reliably, it can be routed to Needs-Review rather than treated as something the model understands.

…

View on GitHub

How I Built It


scan -> read a short snippet -> Gemma names and sorts -> code checks the name

     -> preview -> confirm -> move -> undo log

Gemma suggests, code decides

A tidier moves real files, so a confident wrong answer costs more than a slow one. My rule was: Gemma proposes, and code has the last word.

For each file, Gemma sees the first 1,500 characters of a document (images are shrunk to 896 px) and returns JSON that pydantic validates. It gets one retry, and if that fails the file goes to Needs-Review. Around the model, ordinary code does the safety work:

It never overwrites a file; a name clash gets _2, _3.
It logs every folder it creates, so undo removes only those.
It never reads or moves files with sensitive names (.env, keys, passwords, passport). That's a name check in code, not a model judgment.
It scans the top level only and skips symlinks.
If there's nothing to read (a blank image, an empty or broken file, a format it can't open), it doesn't ask the model at all. The file goes to Needs-Review with its name unchanged.

The bug that taught me where the model belongs

My first prompt told Gemma to rename every file it processed. It did, even the files that already had good names.

So I added an instruction: check whether the original name is already meaningful. That failed in a stranger way. For a file called some.pdf, Gemma wrote a good name, relu_activation_script, and still answered keep some.pdf. It was good at naming a file from its content and unreliable at judging the old name.

I tightened the prompt and added a check in code: the old name is kept only if the model says keep and at least 60% of the old name's words appear in the new name. After both changes, some.pdf, ticket_scan_7 and ticket_scan_77 all came out clean.

Gemma writes the name. Code gets the last word on keeping the old one.

What I measured

Baseline (30 files): Every file landed in the right category (30/30). Three runs gave the same folder and filename for all 30, and undo restored all 30 byte-for-byte. I should be honest about this. I wrote the answer key after earlier runs, and I measured it before the Personal folder and Needs-Review changes without repeating it on the final version. Repeatability also isn't correctness. So treat it as a sanity check, not a benchmark.

First stress test: What worked, and what didn't?

I built a set to break it: generic and misleading names, a double extension, empty and corrupt files, blank images, a scanned PDF, an .xlsx, an .mp3, sensitive filenames and a nested folder. All contents are made up.

The first stress test contained 28 files and one folder containing another file. File-Tidier processed 26 of the 28 files. The remaining two, .env and passwords.txt, were intentionally left untouched by the security rules in the code. The nested folder was also left untouched because the current implementation only processes top-level files.

It exposed both things File-Tidier handled well and cases where it still needed improvement.

Some of the most important behaviours worked as intended:

Empty and unreadable files: broken_document.pdf and the blank document.pdf were sent to Needs-Review. The empty final_v2.txt and blank untitled.docx were also sent there, keeping their original names rather than inventing descriptions.
Content over filenames: flight_ticket.pdf actually contained a restaurant bill. File-Tidier identified the content, renamed it restaurant_bill_example.pdf, and placed it under Receipts. Similarly, meeting_minutes.docx contained a cooking recipe and was renamed cooking_recipe_data.docx.
Useful categorisation: The course completion certificate went to Study, the EV charging invoice went to Receipts, and the weekend packing checklist went to Travel.
Unreadable or unsupported content: scanned_document.pdf was sent to Needs-Review rather than being confidently classified without usable content.

The run also revealed some limitations:

Blank images were still classified as photos. Both IMG_001.jpg and untitled_image.png went to Photos, even though they were blank. The model needed a better way to distinguish an actual photograph from an empty image.
Unsupported files received confident classifications. podcast_recording.mp3 went to Study and monthly_budget.xlsx went to Receipts, even though neither format was supported. Both should have gone to Needs-Review.
Some categories were too broad. At this stage, Personal hadn't been introduced, so personal reminders and private notes ended up in Study. Other mismatches included a grocery list, plant-care instructions and an employment checklist being placed under Study.

The last group of errors helped me identify a limitation in the original category structure. Not every document belongs to a traditional folder like Study, Work or Receipts, and a file can have a perfectly reasonable name while still being placed in the wrong category.

These findings shaped the subsequent changes, including more cautious handling of files without usable content and the introduction of a Personal category. The goal wasn't just to make the demo look cleaner; it was to make File-Tidier more careful about the decisions it couldn't reliably make.

Second stress test: Better handling, but not every decision was right

The second stress test contained 29 files and one folder containing another file. This set included a newly added .tar.gz file, alongside the same .env and passwords.txt files from the first test. File-Tidier processed 27 files; the two security-sensitive files were intentionally left untouched. As in the first test, the nested folder wasn't processed because the current implementation only scans top-level files.

The run took 108 seconds for 27 processed files, averaging about 4 seconds per file.

Several things improved:

Blank images: IMG_001.jpg and untitled_image.png were now sent to Needs-Review instead of being classified as Photos.
Unsupported files: podcast_recording.mp3 was sent to Needs-Review rather than being assigned to Study. The unsupported .tar.gz file was also routed to Needs-Review and placed under Archive because it met the six-month age threshold.
Personal files: Introducing the Personal category helped place grocery_list.txt, cooking_recipe.docx, pasta_recipe.pdf, personal_reminders.txt, and private_notes.docx in more appropriate locations.
Empty or unreadable documents: document.pdf, final_v2.txt, notes.txt, broken_document.pdf, and untitled.docx were sent to Needs-Review. The scanned document was also routed there because its content couldn't be reliably extracted.
Misleading filenames: flight_ticket.pdf was again recognised as a restaurant bill, while receipt.pdf was renamed to reflect its rental-agreement content.

But the second run still exposed some problems:

monthly_budget.xlsx went to Needs-Review because the tool can't read spreadsheets yet. That's the honest outcome for this version, though a person would file it under Personal. Reading .xlsx is on my list.
Three files drifted back to Study. plant_care.txt, short_story.docx and healthy_lifestyle_guide.pdf had been in Personal in an earlier run (I ran the set once between the two tests, with only the Personal folder added). I reworded the category descriptions in the same change as the review handling, and I didn't test the two separately. The boundary between Study, Personal and Work is fragile for a 4B model, and more prompt text doesn't reliably fix it.
recipe.txt contained an employment checklist but was placed under Personal. I'd expect Work, though Personal is defensible.

Why Does Open Innovation Matter?

Your files stay on your machine. Downloads is full of invoices, rental agreements and IDs. With a local model, none of it goes to a third-party API. For a tool that reads your files, this is the strongest reason to go open.
No per-file cost. There are no usage charges for classification. Your laptop spends some electricity, and that's all.
Works offline. After setup and the model download, it runs without internet. I tested it with Wi-Fi off.
No server to maintain. Both the organiser and the watcher run on your own computer, so nothing can be shut down or repriced.
Control. I could change the prompt and put a code check around the model's answers, and the some.pdf problem needed exactly that. In principle I could also swap the model, though I didn't get to compare larger Gemma sizes.

Where a closed model would be better: reading. A larger hosted model would handle scanned PDFs and spreadsheets, and misread fewer image details. It would also be faster on a modest laptop. It would still need the same safeguards, because a confident wrong rename is just as damaging. The preview, the never-overwrite rule and undo exist for that reason, whichever model sits behind them. I think trading some accuracy for private files and no per-file cost is right for this job, but you should weigh it yourself.

The Lazy Payoff

The theme was laziness, so I made the lazy path the main path. Run it once, look at a table and press confirm. Or start the watcher, and it tidies new files once they stop growing, with every batch undoable. It only touches files that arrive after it starts, because lazy mode has no confirm step, so it must never be able to damage something it wasn't asked about.

Did It Actually Save Time?

I also compared one File-Tidier run with a manual sorting attempt on the same 30 files.

Method	Recorded time
File-Tidier, first pass	~5 min 44 sec
Manual sorting	10 min 49 sec

In this trial, File-Tidier finished its first pass about five minutes sooner.

That is promising, but it's only one attempt for each method, not a controlled productivity study. Results will vary with file types, computer performance, and how someone sorts manually.

The longer-term benefit I want to explore is reducing the repeated effort of keeping a folder organised as new files continue to arrive.

Prize Categories

Best Use of Gemma: Gemma 3 4B runs locally through Ollama and does the naming and sorting in the app, and reads the images. I measured where it fails, which was judging names and anything it couldn't read, and built code around those failures.

DEV Community: Hiteshi Kukreja