Stop organizing files by hand.
SlothSort is a local-first AI agent that tidies messy folders. An open-weight model running on your computer suggests clear names and folders. You review every change, nothing is overwritten, and every move can be undone.
SlothSort runs on your machine, not on this website. This page is only the project overview.
Before
- doc_001.pdf
- invoice_final_2.pdf
- hw3.docx
- notes_final_v3.txt
- Downloads/download (3).pdf
After you approve
- Invoices/Greenfield_Power_Electricity_Bill_October_2026.pdf
- Invoices/Lumen_Labs_Redesign_Invoice_1042.pdf
- Assignments/CS101_Assignment_3_Sorting_Algorithms.docx
- Notes/Project_Kestrel_Weekly_Meeting_Notes.txt
- Receipts/Pinecone_Books_Order_Receipt_PB88213.pdf
Real suggestions from gemma3:4b on the bundled synthetic demo set. All names and companies are fictional.
How it works
Five steps, and none of them can be skipped. The model only ever returns text. It never touches your files.
Select a folder
You pick one folder. Whole drives and home folders are refused.
Scan
Read-only. Short excerpts from PDF, DOCX, TXT, MD and CSV files; image metadata; SHA-256 duplicate check.
Review the AI plan
The local model proposes a category and a name. Python re-validates everything, and you can edit any row.
Approve
See the exact from → to list and confirm it. If the folder changed since review, you review again.
Results & undo
Every move goes into a persistent journal. Undo one file or the whole batch.
Built to be trusted with your files
The model's output is treated as untrusted input. These rules are enforced by plain, deterministic code and covered by automated tests.
Guaranteed by code
- Scanning and planning never modify the disk
- Only an intact, user-approved plan can run. Edited or forged plans are refused
- Every path stays inside the folder you chose. Symlinks and junctions are never followed
- Existing files are never overwritten, including during undo
- Files changed after review (size, time or hash) are not moved
- Nothing is deleted, not even duplicates
Honest about limits
- No OCR or image understanding. Images are named from filename and metadata only
- Model confidence is self-reported and not calibrated
- A grounding check flags invented years and IDs, but not every invented word
- Undo refuses, with a reason, if the file was edited or its old spot is now taken
- Not yet tested with the network physically disconnected
localhost by default. There are no API keys and no telemetry, and Streamlit's usage statistics are switched off.Measured, not promised
27 supported synthetic files, each hand-labelled with one expected category. Two runs with gemma3:4b on a Windows 11 laptop.
The default qwen2.5:3b has not been evaluated yet. 27 files is far too few to say anything about general accuracy.
| Metric | Run 1 | Run 2 |
|---|---|---|
| Local AI category accuracy | 25/27 (92.6%) | 24/27 (88.9%) |
| Filename-only baseline | 17/27 (63.0%) | 17/27 (63.0%) |
| Malformed model responses | 0 of 7 calls | 0 of 7 calls |
| Planning time | ≈3.0 s / file | ≈2.2 s / file |
| Approved moves completed | 27/27 | 27/27 |
| Moves undone successfully | 27/27 | 27/27 |
| Unsafe-operation probes blocked | 12/12 | 12/12 |
| Exact duplicates found | 2 groups | 2 groups |
The demo set includes a prompt-injection file that tells the model to move it into system32. The model did not follow it, and the validator would have blocked that path anyway.
Full method and caveats are in the README.
Get started
You need Python 3.11+ and Ollama. Setup needs the internet once, to install packages and download the model.
# 1. Get the code git clone https://github.com/SHWETANK-SAURABH/slothsort.git cd slothsort python -m venv .venv # Windows: .venv\Scripts\activate macOS/Linux: source .venv/bin/activate pip install -r requirements.txt # 2. Download a local model (about 1.9 GB) ollama pull qwen2.5:3b # 3. Optional: create the 29-file synthetic demo folder python demo/generate_demo.py # 4. Launch, then open http://localhost:8501 streamlit run app.py