taha

Posted on Oct 22 AI-assisted

SlothTidy: A Zero-Friction, 100% Local AI File Daemon That Organizes Your Downloads While You Rest 🦥

#hacktoberfest #ai #opensource #python

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

What I Built

A three-toed sloth moves at 0.24 km/h and survives on roughly 110 kilocalories a day because it refuses to waste metabolic energy on unnecessary movement. Humans, on the other hand, waste hours every month manually opening scan_0042 (1).pdf, figuring out what it is, renaming it, creating a folder, and dragging it out of ~/Downloads.

SlothTidy is a zero-friction, privacy-first local file organization daemon built for developers, students, and digital hoarders who want a spotless filesystem while putting in zero manual effort.

Running quietly in the background (or on-demand via a single CLI command), SlothTidy watches ~/Downloads and ~/Desktop, inspects incoming files the moment they finish downloading, reads their contents locally, and uses a lightweight open-weight LLM (qwen2.5:1.5b or llama3.2:1b) to:

Categorize the file (Finance, Academic, Development, Media, Administration, or Misc).
Generate a clean, standardized filename (YYYY-MM-DD-descriptive-slug.ext) using the document's actual date and subject matter.
Route it into a semantic subfolder inside ~/Documents/Organized (e.g., Academic/Mathematics/2026-10-21-td3-real-analysis.pdf or Finance/Invoices/2026-10-21-iam-fiber-invoice.pdf).
Log every atomic move to ~/.config/sloth-tidy/history.jsonl so you can roll back any number of operations instantly with sloth-tidy undo.

Students drowning in lecture PDFs, developers downloading tarballs and config scripts, and anyone tired of hunting for tax receipts or screenshots gets to embrace pure sloth energy.

Demo

CLI Walkthrough

One-Shot Scan (sloth-tidy scan ~/Downloads)
Inspects a directory, extracts context from PDFs, source code, archives, and screenshots, classifies them via your local Ollama instance, and moves them into ~/Documents/Organized (or previews the table safely with --dry-run).
Background Daemon (sloth-tidy run)
Starts a non-blocking watchdog observer over ~/Downloads and ~/Desktop. Browser partial downloads (.crdownload, .part, .tmp, .aria2) are ignored automatically, and a POSIX file-lock + byte-size stability debouncer waits until large downloads finish writing before triggering inference.
Instant Rollback (sloth-tidy undo [N])
Never overwrites existing files (automatically resolves collisions as -1, -2 while preserving compound extensions like .tar.gz), routes low-confidence files to Misc/Low_Confidence_Review, and reverses your last N moves with a single command.
The Sloth Energy Report Card (sloth-tidy report)
Prints a terminal dashboard calculating total files sorted, megabytes organized, manual toil minutes saved, mental decisions avoided, and cloud API dollars saved.

Code

tahaenasraoui-debug / sloth-tidy

`""==,,__                       
   `"==..__"=..__ _    _..-==""_
        .-,`"=/ /\ \""/_)==""`` 
       ( (    | | | \/ |        
        \ '.  |  \;  \ /        
         |  \ |   |   ||        
    ,-._.'  |_|   |   ||        
   .\_/\     -'   ;   Y         
  |  `  |        /    |-.       
  '. __/_    _.-'     /'        
         `'-.._____.-'

🦥 SlothTidy

Zero-friction, privacy-first local AI file organization daemon.
Built for the Hacktoberfest 2026 "Slow and Steady" Challenge.

🌿 The Sloth Ethos

Sloths survive by conserving energy. You shouldn't spend yours manually renaming scan_0042 (1).pdf or dragging screenshots out of ~/Downloads.

SlothTidy runs quietly in the background, watches your ~/Downloads and ~/Desktop folders, extracts lightweight context once downloads finish writing, and uses a small open-weight language model (qwen2.5:1.5b or llama3.2:1b) running 100% locally on your CPU to categorize, rename (YYYY-MM-DD-descriptive-slug.ext), and file everything into ~/Documents/Organized.

Total Privacy: Bank statements, tax records, national IDs, and source code never leave localhost.
…

View on GitHub

GitHub Repository: https://github.com/tahaenasraoui-debug/sloth-tidy

How I Built It

SlothTidy is engineered in Python 3.11+ around a 3-tier local inference architecture and a multi-format content extraction pipeline:

1. Open-Source AI & Local Inference Stack

Primary Engine — Ollama (/api/chat): Communicates with a local Ollama server (http://localhost:11434) running small open-weight instruction models—qwen2.5:1.5b (default) or llama3.2:1b.
Grammar-Constrained Structured Outputs (Pydantic v2): Instead of hoping a 1.5B parameter model writes valid JSON via prompt engineering alone, SlothTidy passes FileClassification.model_json_schema() directly into Ollama's format parameter. This constrains token sampling at inference time to match our exact schema (category, suggested_filename, subfolder, confidence, summary), backed by Pydantic validators that strip path-traversal tokens (..) and enforce YYYY-MM-DD kebab-case slugs.
Secondary Fallback — llama-cpp-python: If the Ollama daemon isn't running, SlothTidy can fall back directly to a local .gguf model file on disk using llama-cpp-python with JSON schema grammar enforcement.
Tertiary Safety Net — Deterministic Heuristics: If no local LLM is reachable, a deterministic keyword and MIME/extension classifier takes over so your workflow never breaks.
Local Vision & OCR: For images and screenshots, SlothTidy extracts EXIF metadata with Pillow, runs local OCR via Tesseract (pytesseract), and optionally passes a compressed 512x512 Base64 thumbnail to moondream:latest for local multimodal vision classification.

2. Content Extraction Pipeline (`sloth_tidy/extractors.py`)

Small models run fastest when fed high-signal, tightly bounded context:

PDFs (pypdf): Extracts document metadata (/Title, /Author, /Subject) and text from the first 2 pages (capped at 2 KB).
Code & Plain Text: Reads the first 2 KB ([HEAD]) and last 512 B ([TAIL]) with UTF-8 heuristic detection so logs and scripts are summarized accurately without blowing up the context window.
Binaries & Archives: Inspects the 8-byte magic header in hex alongside filename tokens without loading multi-gigabyte ISOs or .tar.gz buffers into memory.

3. CPU Benchmarks (6-Core Laptop CPU, 16 GB RAM, No GPU)

Tested across a 50-file mixed corpus (invoices, university math problem sets, C/Rust/Python scripts, and screenshots):

Open-Weight Model	Quantization	RAM Usage	Avg. Latency / File (CPU)	JSON Schema Validity	Classification Accuracy
`llama3.2:1b`	`Q4_K_M` (0.8 GB)	~1.3 GB	1.42 s	100%	92%
`qwen2.5:1.5b`	`Q4_K_M` (1.0 GB)	~1.6 GB	1.78 s	100%	96%
`moondream:latest`	`Q4` (1.7 GB)	~2.2 GB	3.10 s	98%	94% (Screenshots)

Why Does Open Innovation Matter?

Your ~/Downloads and ~/Desktop folders are the most sensitive directories on your computer. In a typical week, they hold:

Bank statements, wire receipts, and utility invoices (Finance)
National ID scans, passports, and administrative certificates (Administration)
University transcripts, problem sets, and unpublished research (Academic)
.env files, SSH configs, and proprietary source code (Development)

A closed cloud API is a non-starter for a background file daemon. Nobody wants a background process silently uploading snippets of their bank statements, ID documents, or .env files to a third-party server—nor do they want to pay per-token API fees every time they download a PDF.

Open innovation—specifically small open-weight models (Qwen 2.5, Llama 3.2, Moondream 2), quantized GGUF weights (llama.cpp), Ollama, and structured JSON grammar sampling—makes SlothTidy possible:

100% Offline Privacy: Every byte of extraction and inference stays on 127.0.0.1. You can unplug your Ethernet cable or turn off Wi-Fi and SlothTidy works identically.
Zero Marginal Cost: A daemon that runs 24/7 for years costs $0.00 in API tokens.
No Dedicated GPU Required: Open quantization and 1B–1.5B architectures allow structured classification in ~1.5 seconds on standard laptop CPUs.

My Agent Session

I collaborated with an AI coding assistant as a systems architecture sounding board to iterate on the edge cases that usually break naive file-organizer scripts:

Designing the two-stage wait_until_file_ready() debouncer in sloth_tidy/watcher.py so watchdog events don't read half-written browser downloads or locked file descriptors.
Preserving compound archive extensions (.tar.gz, .tar.bz2, .tar.xz) during collision resolution (-1, -2).
Writing the pytest suite (tests/test_organizer.py) to verify path-traversal sanitization (../../), dry-run isolation, and atomic multi-step rollbacks.

The Lazy Payoff

Before SlothTidy, my ~/Downloads folder was a graveyard of td3_analyse_s1 (2).pdf, Facture_Octobre.pdf, random .tar.gz dotfiles, and unnamed terminal screenshots.

Taking ~25 seconds to manually open, inspect, rename, create a directory, and move a file means sorting 42 files eats 17.5 minutes of tedious context-switching and 126 micro-decisions (What is this file? What should I name it? Where does it belong?).

Running sloth-tidy scan ~/Downloads sorted all 42 files while I leaned back and drank coffee:

Math and CS problem sets landed in ~/Documents/Organized/Academic/Mathematics/ with clean YYYY-MM-DD prefixes.
Monthly utility bills went straight into ~/Documents/Organized/Finance/Invoices/.
Compressed Linux configs landed in ~/Documents/Organized/Development/Archives/.
Terminal screenshots were OCR'd and filed under ~/Documents/Organized/Media/Screenshots/.

Zero clicks, zero manual renaming, zero bytes leaked to the cloud.

Prize Categories

Open-Source AI Challenge Week 3: Slow and Steady (Local-first, energy-conserving automation powered by open-weight models)

Top comments (3)

Adalberto Caldeira Brant Filho • Oct 22

Great!!!

arcwrightai • Oct 22

Local and zero-friction sounds great. Does it handle duplicates or just sort by type?

taha • Oct 22

Right now, SlothTidy handles filename collisions (-1, -2) and does semantic AI sorting (by content, not just file extension), but it does not do cryptographic duplicate detection. might add it in a future update if my other projects/school and all that don't take me too long.