downloads-organizer

name	downloads-organizer
description	Automatically organize and clean up downloads folder by categorizing files, removing duplicates, and optimizing storage space
license	Apache-2.0

Downloads Organizer

Automatically organize and clean up your downloads folder with intelligent file categorization, duplicate detection, and storage optimization.

Overview

Transform a chaotic downloads folder into a well-organized, searchable archive by:

• Categorizing files - Organize by type (documents, images, videos, installers, etc.)
• Removing duplicates - Detect and eliminate duplicate files
• Cleaning old files - Remove outdated installers and temporary files
• Generating reports - Provide detailed analysis of storage usage
• Scheduled cleanup - Set up automated maintenance

Basic Workflow

1. Analyze Downloads Folder

Get current state:

cd ~/Downloads
python scripts/organizer.py --analyze

Output:

📊 Downloads Folder Analysis
Total Size: 45.2 GB
Total Files: 1,234
Total Folders: 87

Largest Files:
1. alma-0.0.204-mac-arm64.dmg (248 MB)
2. Antigravity.Tools_3.3.32_aarch64.dmg (14 MB)

File Distribution:
- Installers: 3.6 GB (8%)
- Documents: 662 MB (1.5%)
- Images: 1.2 GB (2.7%)
- Videos: 5.8 GB (12.8%)

2. Organize Files

Auto-categorize scattered files:

python scripts/organizer.py --organize --dry-run

Preview:

Would move:
- *.dmg → Installers/ (15 files)
- *.png → Images/ (42 files)
- *.pdf → Documents/PDF/ (23 files)
- *.mp4 → Videos/ (8 files)
- *.json → Documents/ (12 files)

Execute:

python scripts/organizer.py --organize

3. Clean Up

Remove old and duplicate files:

python scripts/organizer.py --cleanup

Actions:

• Remove installers older than 60 days
• Delete duplicate files
• Remove empty folders
• Clean temporary files

4. Generate Report

Get detailed report:

python scripts/organizer.py --report --output report.md

Organization Rules

File Type Categories

Documents:

• *.pdf, *.doc, *.docx, *.txt, *.md, *.rtf
• *.xls, *.xlsx, *.csv, *.json, *.yaml, *.yml

Images:

• *.png, *.jpg, *.jpeg, *.gif, *.svg, *.webp, *.bmp
• *.tiff, *.ico

Videos:

• *.mp4, *.mov, *.avi, *.mkv, *.webm, *.flv

Audio:

• *.mp3, *.wav, *.m4a, *.flac, *.aac, *.ogg

Installers:

• *.dmg, *.pkg, *.app, *.zip, *.tar.gz, *.rar
• *.exe, *.msi

Archives:

• *.zip, *.tar.gz, *.tgz, *.rar, *.7z

Code:

• *.py, *.js, *.ts, *.java, *.cpp, *.c, *.h
• *.html, *.css, *.scss, *.json

Data:

• *.csv, *.tsv, *.sql, *.db, *.sqlite

Folder Structure

~/Downloads/
├── Archives/          # Compressed archives
├── Audio/             # Audio files
├── Backups/           # Backup files and folders
├── Documents/         # Documents and text files
│   ├── PDF/
│   └── Spreadsheets/
├── Images/            # Image files
├── Installers/        # Software installers
├── Projects/          # Project-related folders
├── Videos/            # Video files
├── Software/          # Application bundles
└── Others/           # Miscellaneous files

Cleanup Strategies

Time-Based Cleanup

Installers:

• Remove *.dmg, *.pkg files older than 60 days
• Keep only recent installers (last 2 months)

Temporary Files:

• Remove *.tmp, *.temp, *.cache files
• Clean ~/.Trash contents

Empty Folders:

• Remove directories with 0 files
• Remove directories older than 90 days with < 5 files

Duplicate Detection

Find duplicates by:

• File name - Exact name match
• File size - Same size (quick filter)
• Hash comparison - MD5/SHA256 for exact duplicates

Action:

python scripts/organizer.py --find-duplicates

Keep strategy:

• Keep newest file
• Keep file with shortest path
• Ask user for conflicts

Large File Analysis

Identify space hogs:

python scripts/organizer.py --large-files --min-size 100MB

Output:

📦 Large Files (>100MB):
1. alma-0.0.204-mac-arm64.dmg - 248 MB
2. recording_2026-01-10_23-22-53.mp4 - 12 MB
3. generated-1768282547017.png - 25 MB

Automated Maintenance

Schedule Cleanup

Set up cron job for automatic cleanup:

# Run cleanup every Sunday at 2 AM
0 2 * * 0 cd ~/Downloads && python scripts/organizer.py --cleanup

# Run organization daily at 9 AM
0 9 * * * cd ~/Downloads && python scripts/organizer.py --organize

Automated Rules

Define custom rules in config/rules.yaml:

patterns:
  - pattern: "*_recording_*.mp4"
    destination: Videos/Recordings/
    keep_days: 30

  - pattern: "generated-*.png"
    destination: Images/Generated/
    keep_days: 7

  - pattern: "Screenshot*.png"
    destination: Images/Screenshots/
    keep_days: 30

Configuration

Settings File

Create ~/.downloads-organizer/config.yaml:

downloads_dir: ~/Downloads
dry_run: false
verbose: true

cleanup:
  installer_age_days: 60
  temp_age_days: 7
  duplicate_action: keep_newest

organization:
  auto_categorize: true
  respect_existing_folders: true
  create_missing_folders: true

exclusions:
  - "*.locked"
  - ".*"
  - "node_modules"
  - ".git"

Custom Categories

Add custom file types to categories:

custom_categories:
  design:
    extensions: [".sketch", ".fig", ".psd", ".ai"]
    folder: "Design/"

  data_science:
    extensions: [".ipynb", ".r", ".mat", ".h5"]
    folder: "DataScience/"

Usage Examples

Example 1: Weekly Maintenance

# Full cleanup cycle
python scripts/organizer.py \
  --organize \
  --cleanup \
  --report \
  --output ~/Downloads/weekly-report.md

Example 2: Quick Organize

# Just organize new files
python scripts/organizer.py --organize --new-only

Example 3: Deep Clean

# Aggressive cleanup with confirmation
python scripts/organizer.py \
  --cleanup \
  --installer-age 30 \
  --remove-duplicates \
  --remove-empty-folders \
  --confirm

Example 4: Project Cleanup

# Move project files to Projects/ folder
python scripts/organizer.py \
  --move-projects \
  --project-pattern "*-project*" \
  --destination Projects/

Integration

Obsidian Integration

Link organized files to Obsidian vault:

python scripts/organizer.py --link-obsidian --vault ~/Documents/ObsidianVault

Creates:

• [[Downloads/Images/file.png]] links in Obsidian
• Daily notes with new files
• Mappings for easy searching

Cloud Sync Integration

Sync organized folders to cloud:

python scripts/organizer.py --sync-cloud \
  --provider icloud \
  --folders Documents,Images \
  --exclude-backups

Notification Integration

Send cleanup notifications:

python scripts/organizer.py --cleanup --notify \
  --method slack \
  --channel #downloads

Best Practices

Organization

✅ DO:

• Organize regularly (daily or weekly)
• Use consistent folder structure
• Keep recent installers accessible
• Archive important files to permanent locations

❌ DON'T:

• Wait until downloads folder is huge
• Mix unrelated file types
• Delete files without reviewing
• Keep old installers "just in case"

Cleanup

✅ DO:

• Set appropriate age thresholds
• Review duplicates before deleting
• Check large files before cleanup
• Backup important files first

❌ DON'T::

• Delete files blindly
• Set too aggressive cleanup
• Ignore duplicate warnings
• Skip backup checks

Performance

✅ DO:

• Schedule cleanup during low activity
• Use dry-run first
• Monitor disk space after cleanup
• Keep logs for troubleshooting

❌ DON'T:

• Run cleanup while downloading
• Organize during file transfers
• Disable safety checks
• Ignore error messages

Troubleshooting

File Move Conflicts

Problem: "File already exists" error

Solution:

python scripts/organizer.py --organize --handle-conflicts ask

Options:

• ask - Prompt for each conflict
• skip - Skip conflicting files
• overwrite - Overwrite existing files
• rename - Add timestamp to new files

Permission Errors

Problem: "Permission denied" when moving files

Solution:

# Fix permissions
chmod -R u+rw ~/Downloads

# Run with sudo (last resort)
sudo python scripts/organizer.py --cleanup

Slow Performance

Problem: Organization takes too long

Solution:

# Exclude large directories
python scripts/organizer.py --exclude "Projects/,Backups/"

# Use parallel processing
python scripts/organizer.py --parallel --workers 4

# Skip hash comparison for duplicates
python scripts/organizer.py --find-duplicates --quick

Resources

• Main script: scripts/organizer.py
• Configuration guide: references/configuration.md
• File type mappings: references/file-types.yaml
• Troubleshooting: references/troubleshooting.md

Safety Features

Backup Before Cleanup

Always create backup before major cleanup:

python scripts/organizer.py --backup --dest ~/Downloads-backup

Undo Functionality

Roll back changes:

python scripts/organizer.py --undo --from ~/Downloads-backup

Confirmation Prompts

Confirm destructive actions:

python scripts/organizer.py --cleanup --confirm

Logging

Detailed logging for audit:

python scripts/organizer.py --organize --log-level debug --log-file organizer.log

---

Last Updated: 2026-01-15 Version: 1.0.0