Folder Organizer

A small command-line tool that cleans up a messy folder: sorts files into subfolders by type and optionally renames them with a date prefix. Never deletes anything — only moves and renames. Handles name collisions safely.

Standard-library Python only. No dependencies, no config file, no surprises.

---

What it does

• Groups files into Images, Documents, Spreadsheets, Code, Archives, Audio, Video, and Other based on extension.
• Optionally prepends YYYY-MM-DD_ to each file's name using its modification time, so time-sorted browsing still works after sorting by type.
• Skips existing subfolders and hidden files — only touches the flat contents of the target folder.
• Detects name collisions and appends _1, _2, ... to keep every file.
• Includes a --dry-run flag so you can preview the plan before anything moves.

Safe by construction: uses shutil.move (never delete), skips directories (never recurse without asking), and prints every move it makes.

---

Usage

python organize.py <folder>                # organize into subfolders
python organize.py <folder> --dry-run      # show the plan, move nothing
python organize.py <folder> --date-prefix  # also rename YYYY-MM-DD_name
python organize.py                         # organizes the current directory

Examples:

python organize.py ~/Downloads/mess
python organize.py ~/Downloads/mess --dry-run
python organize.py ~/Downloads/mess --date-prefix

Sample dry-run output:

Scanning /Users/weli/Downloads/mess ...
  [dry-run] receipt.pdf  ->  Documents/receipt.pdf
  [dry-run] logo.png     ->  Images/logo.png
  [dry-run] budget.xlsx  ->  Spreadsheets/budget.xlsx
  [dry-run] main.py      ->  Code/main.py

Would move 4 files:
  Images         1
  Documents      1
  Spreadsheets   1
  Code           1

---

Deliverable & screenshots

• Folder-Organizer-Deliverable.pdf — one-pager describing scope, approach, and result.
• screenshots/ — captures of the tool running end-to-end on real folders.

---

Built by

I build AI-agent and automation systems — Claude Code / MCP integrations, LLM-into-workflow tooling, scrapers, and scripts that kill repetitive work. If you need a small utility that handles a repetitive task, that's the work I do.

• Upwork: its_weli on Upwork
• Contact: hello@weli.build

---

License

MIT — use it, fork it, ship it.