ClutterCtrl

A fast, lightweight terminal file organizer. It cleans up cluttered folders (like your Downloads or Desktop), sorts files into organized directories by type, lets you preview changes before touching anything, and keeps a dedicated log of every run so you can undo changes with a single command.

Written in pure Python with standard library modules, so you can run it immediately without installing any third-party packages.

Features

• Zero-Dependency CLI: Runs directly in Windows Command Prompt, PowerShell, macOS Terminal, or Linux using standard Python.
• Dedicated Run Logs: Every organization run creates its own log file (run_YYYY-MM-DD_HH-MM-SS_<id>.log) recording the exact before and after paths for every file moved.
• 1-Click Undo: Revert any previous run instantly via clutterctrl undo <Run ID> or through the interactive menu.
• Dry Run Previews: Check file lists, categories, destination paths, and sizes in a clean table before anything gets moved.
• Background Folder Watcher: Optionally watch folders like Downloads to auto-sort new files as they arrive, with built-in debounce so it never touches partial downloads.
• Standard and Deep Scans: Choose between organizing top-level files or scanning entire folder trees recursively while cleaning up empty folders.
• Safe Renaming: Never overwrites existing files. If a file with the same name exists, it automatically adds a counter (like photo_1.png).
• Stats & History: View your past runs and see a visual bar chart of how your storage is organized across categories.

Supported Categories

Images · Videos · Audio · Documents · Code & Web · Projects & Creative · Data & Databases · Archives · Executables · Fonts · Misc

Quickstart

1. Run Directly (No Setup Needed)

You can clone the repo and run ClutterCtrl right away:

git clone https://github.com/az1213-dev/clutter-ctrl.git
cd clutter-ctrl

# Run in Windows CMD or PowerShell
python clutterctrl/main.py

2. Install as a Global Command

If you want to use the clutterctrl command anywhere in your terminal, install it in editable mode:

pip install -e .

# Or with pipx
pipx install .

Now you can run clutterctrl from any directory.

CLI Commands

You can run ClutterCtrl with subcommands or launch the interactive menu by running clutterctrl with no arguments:

# Open the interactive terminal menu
clutterctrl

# Preview what will be moved in Downloads without changing anything
clutterctrl scan "C:\Users\Username\Downloads"

# Preview a folder recursively (Deep Scan)
clutterctrl scan "D:\Projects" --deep

# Clean and organize Downloads right away
clutterctrl clean "C:\Users\Username\Downloads"

# Clean an entire directory tree recursively
clutterctrl clean "D:\MessyFolder" --deep

# Watch a folder in the background and sort files as they arrive
clutterctrl watch "C:\Users\Username\Downloads"

# View past organization runs
clutterctrl history

# Undo the most recent run
clutterctrl undo

# Undo a specific run by ID
clutterctrl undo run_2026-08-31_13-52-17_aad725

# View storage statistics and category distribution
clutterctrl stats

# View extension mapping rules
clutterctrl rules

Run Logs and Undo

ClutterCtrl creates a dedicated log file for every run inside the repository:

• Log Path: clutterctrl/logs/run_*.log

What a Run Log Looks Like

Run ID: run_2026-08-31_13-52-17_aad725
Run started: 2026-08-31T13:52:17.123456
Target: C:\Users\Username\Downloads
Deep Scan: False
Mode: clean
Status: ACTIVE

--- OPERATIONS ---
MOVED: C:\Users\Username\Downloads\photo.png -> C:\Users\Username\Downloads\Images\photo.png | Category: Images | Size: 1048576
MOVED: C:\Users\Username\Downloads\report.pdf -> C:\Users\Username\Downloads\Documents\report.pdf | Category: Documents | Size: 524288

--- SUMMARY ---
Total files moved: 2
Images: 1
Documents: 1
Total bytes: 1572864
Run completed: 2026-08-31T13:52:17.456789
Status: COMPLETED

When you undo a run, ClutterCtrl reads the operations in reverse, puts all files back in their original folders, and marks the log as UNDONE.

Running Tests

You can run the test suite with pytest:

pytest -v

License

This project is open source and available under the MIT License. See LICENSE for details.