File Butler: The Sloth-Inspired AI Directory Organizer

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

What I Built

File Butler is an intelligent, Python-based directory organizer that channels your inner sloth by automating the tedious task of sorting messy folders (like your Downloads or Desktop). When pointed at a target directory, File Butler scans the files and subfolders, uses an open-weight model to determine a clean taxonomic folder structure, and safely moves everything into its proper place, saving you hours of manual sorting.

Demo

Code

GitHub Repository: File Butler

How I Built It

File Butler is built using pure Python (pathlib, shutil, and argparse) and is powered by an open-weight model (openai/gpt-oss-20b) via the Groq API.

• Directory Scanner: Inspects loose files and subfolders while bypassing hidden system files.
• AI Taxonomy Engine: Sends a lightweight JSON map of the directory structure to the open-weight model to generate a logical categorization plan.
• Safety & Safeguards: Includes a dry-run mode (--dry-run) to preview changes, an interactive human-in-the-loop confirmation prompt, and an edge-case handler that gracefully detects when a folder is already organized.
• Audit Trail: Automatically records all moved items and errors into a persistent file_butler.log file.

Why Does Open Innovation Matter?

Leveraging open-weight models through high-performance cloud inference (Groq) allowed File Butler to process directory structures instantly without requiring a heavy local GPU or proprietary vendor lock-in. Furthermore, using a lightweight open-weight model keeps inference costs virtually zero, ensuring the utility runs comfortably within free developer tier limits while remaining fast and adaptable.

The Lazy Payoff

Instead of wasting mental energy and precious weekend time dragging hundreds of loose files into custom folders one-by-one, File Butler organizes an entire cluttered directory in a single keystroke. It turns a dreaded weekly chore into a one-second background task, letting you lean back, relax, and channel your inner sloth.