AI-powered PC file organizer and cleaner that automatically categorizes your files, detects duplicates, cleans up junk, and organizes your folders with smart rules. No more messy desktops or lost documents.
- Features
- How It Works
- AI Classification
- Duplicate Detection
- Tech Stack
- Installation
- Configuration
- Usage Guide
- CLI Commands
- Rules Engine
- Screenshots
- Roadmap
- FAQ
- Troubleshooting
- Contributing
- License
- ✔ AI Content Classification — Analyzes file content (not just extension) to categorize into 50+ categories: Documents, Images, Videos, Audio, Archives, Code, Projects, Fonts, Templates, and more
- ✔ Duplicate & Near-Duplicate Detection — Perceptual hashing for images, content hashing for docs, fuzzy match for text files. Finds exact copies AND similar files
- ✔ Smart Cleanup — Identifies temp files, cache, old downloads (>90 days), empty folders, log files, crash dumps, and duplicate backups
- ✔ Auto-Organize Rules Engine — Rule-based organizer: move, copy, rename, archive, compress, or delete based on type, size, date, pattern matching
- ✔ Visual Dashboard — Interactive pie charts, storage trends over time, file type breakdown, largest files list, cleanup recommendations
- ✔ Safe Mode with Full Undo — Every action is previewed before execution. Full undo/redo history — revert any change with one click
- ✔ Scheduled Cleanup — Set it and forget it: daily/weekly/monthly auto-clean with configurable rules
- ✔ Exclusion Manager — Exclude specific folders, file types, or patterns from scanning and cleanup
- ✔ Export Reports — Save scan results and organization history as HTML, PDF, or CSV
- ✔ Multi-Folder Monitoring — Watch multiple folders for changes and auto-organize new files in real-time
┌─────────────────────────────┐
│ Smart Folder Cleaner │
│ (Python) │
└──────────┬──────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Scanner │ │ Classifier │ │ Duplicate │
│ (File tree)│───►│ (AI Engine) │───►│ Detector │
└──────────────┘ └──────┬───────┘ └──────┬───────┘
│ │
┌────────────────────┘ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Rules │ │ Preview │
│ Engine │─────── Review ──────────►│ & Apply │
└──────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ Undo │
│ History │
└──────────────┘
- Scanner walks the folder tree, collects metadata (size, date, hash, type)
- AI Classifier reads content samples, assigns category (Document/Image/Video/etc.)
- Duplicate Detector compares hashes, finds exact copies + near-duplicates
- Rules Engine matches files against user-defined rules (move, delete, archive...)
- Preview shows all proposed changes with diff view — approve or reject each
- Apply executes approved actions with full undo support
Smart Folder Cleaner uses two classification modes:
- Uses file extension + magic bytes + filename pattern analysis
- Categorizes into 50+ types: PDF, DOCX, XLSX, JPG, PNG, MP4, ZIP, TAR, PY, JS, CSS, HTML, JSON, XML, CSV, PPTX, ODT, EPUB, MOBI, FONTS, TTF, OTF, EXE, MSI, DLL, SRC, MD, YAML, ENV, LOG, TMP, CACHE, BAK, ISO, DMG, APK, DEB, RPM, ...
- Zero dependencies — works completely offline
- Speed: ~10,000 files/second
- Uses OpenAI / Gemini API to analyze file content and context
- Understands semantic categories: "Invoice", "Contract", "Screenshot", "Backup", "Project Config"
- Auto-generates folder names and subfolder structures
- Speed: ~50 files/second (API dependent)
| Feature | Local | AI |
|---|---|---|
| Speed | 10K files/s | 50 files/s |
| Categories | 50+ (by type) | Unlimited (semantic) |
| Internet | Not needed | Required |
| Cost | Free | API usage fees |
| Schema detection | ❌ | ✅ Smart sorting |
| Method | Algorithm | Use Case |
|---|---|---|
| Exact | SHA-256 hash | Identical files (byte-perfect) |
| Fuzzy (Images) | Perceptual hash (pHash) | Similar images, thumbnails, resized versions |
| Fuzzy (Text) | Cosine similarity + MinHash | Similar documents with minor edits |
| Name Similar | Levenshtein distance | Files with similar names (e.g., report(1).pdf) |
| Size + Date | Threshold comparison | Potential duplicates within time windows |
Results are grouped with confidence scores:
Duplicates Found: 47 groups (124 files, 2.3 GB)
├─ 📄 report-final.pdf (2.4 MB) ──► report.pdf (2.4 MB) [100% match]
├─ 🖼️ IMG_2024.jpg ──► IMG_2024(2).jpg [100%] ──► IMG_2024_thumb.jpg [89% match]
├─ 📁 backup_2024-01-15.zip ──► backup_2024-01-16.zip [95% match]
└─ 📝 notes_v1.txt ──► notes_v2.txt [72% match (similar text)]
| Component | Technology |
|---|---|
| Language | Python 3.10+ |
| UI | CustomTkinter |
| AI | OpenAI / Gemini API + local classifier |
| Image Hashing | ImageHash + Pillow |
| Text Similarity | scikit-learn (cosine similarity) |
| File Watching | watchdog |
| Charts | Matplotlib |
| Storage | SQLite |
| Reports | ReportLab (PDF) + Jinja2 (HTML) |
| Platform | Windows / Linux |
git clone https://github.com/zougar99/Smart-Folder-Cleaner-Pro.git
cd Smart-Folder-Cleaner-Pro
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.pygit clone https://github.com/zougar99/Smart-Folder-Cleaner-Pro.git
cd Smart-Folder-Cleaner-Pro
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.pyEdit config.yaml:
scan:
include_paths:
- C:\Users\<USER>\Desktop
- C:\Users\<USER>\Downloads
- C:\Users\<USER>\Documents
exclude_paths:
- C:\Windows
- C:\Program Files
exclude_patterns: ['*.sys', '*.dll', 'node_modules/']
max_depth: 10
follow_symlinks: false
classifier:
mode: local # local | ai
ai_provider: openai # openai | gemini
api_key: <YOUR_API_KEY> # only needed for AI mode
cleanup:
temp_files_older_than: 30 # days
recycle_bin: true
empty_folders: true
compress_archives: false
schedule:
enabled: false
frequency: weekly # daily | weekly | monthly
day: sunday
time: "03:00"
rules:
- name: Organize Images
match: type == Image
action: move
target: "C:\Pictures\{year}\{month}"
- name: Delete Old Logs
match: pattern == "*.log" AND age > 90
action: delete
- name: Archive Projects
match: type == Code AND age > 365
action: compress
target: "C:\Archives\{name}.zip"| Step | Action |
|---|---|
| 1 | Launch: python main.py |
| 2 | Click Add Folder and select directories to scan |
| 3 | Choose classification mode (Local / AI) |
| 4 | Toggle duplicate detection on/off |
| 5 | Click Start Scan — progress bar shows real-time status |
| 6 | Review results in the Dashboard tab |
| 7 | Switch to Actions tab to preview all changes |
| 8 | Approve or reject each action |
| 9 | Click Apply to execute |
| 10 | Check History tab to undo any action if needed |
# Scan specific folders
python main.py --scan C:\Users\You\Desktop C:\Users\You\Downloads
# Quick cleanup (temp + cache only)
python main.py --clean --quick
# Full scan with AI classification
python main.py --scan . --ai --api-key YOUR_KEY
# Find duplicates only
python main.py --dedup --scan D:\Photos
# Dry run (preview only, no changes)
python main.py --scan . --dry-run
# Export report
python main.py --scan . --export report.html
# Run as a scheduled task (once)
python main.py --scan . --apply --headlessRules use a simple DSL:
match: type == Image AND size > 5MB AND age > 30
action: compress
target: "C:\Compressed\{year}-{month}"| Condition | Operators | Example |
|---|---|---|
type |
==, != |
type == Document |
ext |
==, !=, in |
ext in ["jpg", "png", "gif"] |
size |
>, <, >=, <= |
size > 100MB |
age |
>, < |
age > 365 (days) |
pattern |
== (glob) |
pattern == "*.tmp" |
name |
contains, matches |
name contains "backup" |
| Action | Description |
|---|---|
move |
Move file to target folder |
copy |
Copy file to target folder |
rename |
Rename with pattern {date}_{name} |
delete |
Move to Recycle Bin |
compress |
Create ZIP archive |
tag |
Apply color tag / label |
(Screenshots coming soon. PRs welcome!)
| Dashboard | Scan Results | Rules Editor |
|---|---|---|
 |
 |
 |
- 🟢 Real-time folder watcher (auto-organize new files)
- 🟡 Cloud backup integration (Google Drive, OneDrive)
- ⚫ Android/iOS companion app
- ⚫ Photo duplicate detection by EXIF data
- ⚫ File versioning system (like macOS Time Machine)
- ⚫ Network drive / NAS support
Yes, it's safe. By default, deleted files go to Recycle Bin. All changes are previewed before execution. Every action is fully undoable from the History tab.
Yes — any locally accessible drive (including NAS and network shares) can be scanned.
Local mode is ~95% accurate for file-type categories. AI mode is ~98% accurate and can understand semantic categories (e.g., "Invoice" vs "Contract").
Yes — enable the scheduler in config.yaml for automatic daily/weekly/monthly cleanup.
Typical users recover 5-50 GB on first scan (temp files, duplicates, old downloads). Heavy users on first scan have recovered up to 200+ GB.
| Problem | Solution |
|---|---|
| Scan is too slow | Switch to Local classification; exclude system folders; reduce depth |
| AI classification fails | Check API key in config; ensure internet connection |
| Duplicate detection misses files | Enable fuzzy matching in Settings; try all hash methods |
| Rules not firing | Check condition syntax in config; verify file matches criteria |
| Undo history lost | Undo data is stored for 30 days in ~/.sfcp/undo/ |
| High memory usage | Reduce scan scope; close other apps; use 64-bit Python |
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push (
git push origin feature/amazing-feature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Made with 🧹 and ❤️ by zougar99