🦥 TidySloth CLI: The Local-First File Organizer That Embraces Sloth Mode

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

What I Built

TidySloth CLI is a lightweight, privacy-focused, local-first Python command-line utility designed to automate digital file organization.

Instead of spending precious time sorting messy Downloads, Desktop, or project folders, TidySloth scans your target directory, categorizes clutter into clean subfolders (Code, Documents, Images, Archives, and Others), and generates a clear Markdown summary index (TIDY_INDEX.md). It channels your inner sloth by handling the tedious file cleanup you keep putting off—all in milliseconds on your own machine.

Demo

Here is tidysloth-cli in action inside VS Code:

Key Features:
scan mode: Previews file distribution and updates the index without moving anything.

tidy mode: Safely organizes files into categorized subfolders.

--dry-run flag: Lets you preview exact move operations risk-free.

TIDY_INDEX.md Generation: Keeps a clean Markdown manifest of all organized files.

Code

RiyaDhami13 / tidysloth-cli

A local-first Python file-organizer CLI that cleans up digital clutter at sloth speed.

🦥 tidysloth-cli

A local-first Python file-organizer CLI that cleans up digital clutter at sloth speed. Built with GitHub Copilot.

Features

• Organizes files into category folders: Code, Documents, Images, Archives, and Others
• Uses pathlib for safe path handling and argparse for CLI parsing
• Supports a non-destructive preview mode with --dry-run
• Generates a clean markdown summary index (TIDY_INDEX.md) for both scan and tidy runs

Requirements

• Python 3.8+

Usage

Run from this repository root:

python tidysloth.py --help

Scan a directory

Scans files and writes TIDY_INDEX.md with category counts and file listings.

python tidysloth.py scan --path ./target_folder

If no target is provided, the current directory is used:

python tidysloth.py scan

Tidy a directory

Moves files into category subfolders and updates TIDY_INDEX.md.

python tidysloth.py tidy --path ./target_folder

Dry run

Preview all move operations without changing any files:

python tidysloth.py tidy --path ./target_folder --dry-run

File categorization

• Code…

View on GitHub

How I Built It

TidySloth was engineered from the ground up using GitHub Copilot as an AI pair programmer.

Built using Python standard libraries (pathlib for safe cross-platform file system operations and argparse for subcommands), GitHub Copilot assisted across the entire build workflow:

1. CLI Architecture: Copilot scaffolded clean subcommand parsing (scan and tidy).

2. Safe File Operations: Assisted in implementing dry-run previews, collision prevention, and directory creation logic.

3. Markdown Generation: Automated the string formatting logic for generating the TIDY_INDEX.md report.

Why Does Open Innovation Matter?

Digital file clutter often contains sensitive information—personal documents, private code snippets, financial records, or configuration files.

100% Private & Offline: TidySloth processes everything locally. Your private filenames and directory contents are never transmitted to cloud servers or third-party APIs.

Zero Cost & Latency: Runs instantly with zero cloud dependencies, API keys, or subscriptions.

Reliable Local Execution: It works anywhere—on a flight, off the grid, or on low-power devices.

My Agent Session

The Lazy Payoff

Sorting a cluttered downloads directory manually usually takes 10–15 minutes of tedious drag-and-drop effort. TidySloth completes the same job in less than 1 second. I used it this week to clean up my messy project workspace and instantly generate structured Markdown indexes without breaking my focus.

Prize Categories

Best Use of GitHub Copilot (Built using GitHub Copilot for code architecture, CLI parsing, and Markdown generation).

Thanks for reading
!