Cleanfy — Intelligent Desktop Robot Vacuum & Physics-Based Organizer

🇹🇷 Türkçe • 🇺🇸 English

Physics-simulated, LiDAR-scanning, and 100% safe desktop organization robot for Windows 10 and 11.
Turn your desktop into a living playground: Matter.js collision physics, regional arrangement with Selection Box, smart classification, and one-click undo.

Cleanfy is an open-source desktop application that transforms your Windows desktop from a boring list of files into a living physics ecosystem. While offering a realistic robot vacuum simulation that roams freely across your screen, dodges obstacles, and sweeps dust with rotating brushes, it works behind the scenes to organize all files on your desktop into pristine folders following a safe, reversible, and rule-based hierarchy.

Getting Started • Features • Selection Box • Architecture • Safety Guarantee • Türkçe Dokümantasyon

▲ Realistic 2.5D robot vacuum, LiDAR scanning laser, spinning brushes, and Matter.js rigid-body collision physics

---

Table of Contents

• Project Vision
• Features
• Regional Custom Arrangement with Selection Box
• Architecture & Operating Principles
• Folder & Category Hierarchy
• Absolute Safety & Data Integrity Guarantee
• Quick Start & Installation
• Glassmorphism Control Panel
• Undo & Reporting
• Zero Lag & Optimized Physics Engine
• Frequently Asked Questions (FAQ)
• SEO Keywords
• License & Author

---

Project Vision

Traditional desktop cleaners and cleanup scripts are typically dull, soulless, and risky utilities. You press a button, and files vanish without you ever seeing where they went.

Cleanfy reimagines this experience from the ground up:

1. Visual & Kinetic Experience: Your desktop icons become real physical bodies. The robot vacuum patrols your screen just like cleaning a room, sweeps files with LiDAR beams, and gently nudges icons with its front bumper.
2. User-Controlled Natural Language Placement: With the Selection Box tool, you can select any corner of your screen (such as the top-right corner or a left column) with your mouse and specify "put only games here" or "arrange only folders here".
3. Zero Risk & Trust: Files are never deleted or overwritten; every single step is guarded by SHA-256 hash verification and can be reverted to its original state with a single click.

---

Features

• Realistic 2D/2.5D Robot Vacuum Simulation:
  • Independently rotating top LiDAR laser turret and blue scanning cone beam.
  • Front optical and ultrasonic proximity sensors.
  • Spring-loaded, flexible front collision bumper.
  • Dual underbody spinning side brushes and dynamic floor dust particles.
• Matter.js 2D Rigid Body Physics:
  • Real mass, friction, and restitution coefficients.
  • Icons slide and bounce against each other realistically when nudged by the robot.
  • Icons maintain upright orientation (angle = 0), ensuring titles and badges remain permanently readable.
• Selection Box & Regional Organization:
  • Draw custom rectangular zones anywhere on the screen.
  • Natural language Turkish/English prompt support or single-click category chip presets.
  • Automatically shifts mismatched files out of the designated zone and arranges target files into a neat, disciplined grid.
• Compact Glassmorphism Control Menu:
  • Minimalist, collapsible HUD in the top-right corner with fluid spring animations.
  • Elegant badge profile on initial launch that never obscures your desktop workflow.
• Smart Category Recognition:
  • 13 primary categories and dozens of subfolder types.
  • Game shortcut intelligence that automatically detects .url Steam, Epic Games, and Riot shortcuts.
• Reversible & SHA-256 Verified Operations:
  • Every completed file transfer can be reverted with one click (UndoSession).
  • Session reports exportable in HTML, JSON, and Excel-compatible CSV (UTF-8 BOM).

---

Regional Custom Arrangement with Selection Box

Rather than sweeping the entire desktop indiscriminately, Cleanfy lets you designate and customize specific zones:

▲ Rectangular on-screen area drawing, natural language request ("Put only games here"), plan confirmation, and automated grid alignment

1. Click the Select Zone & Custom Arrange (Alan Seç & Özel Diz) button in the top-right menu.
2. Drag your mouse across the desktop to draw a rectangle over your desired area.
3. In the pop-up Glassmorphism dialog, pick from quick chips (🎮 Games Only, 📁 Folders Only, 📦 Archives Only, ☕ Jar & Code, etc.) or type a natural language prompt.
4. Click + Add Zone to Plan, then hit Confirm Plan & Arrange to have your files systematically aligned in your selected zone.

---

Architecture & Operating Principles

flowchart TD
    A["Windows Desktop Initialization (Electron + PowerShell API)"] --> B["Real Desktop Path Discovery (OneDrive & Registry)"]
    B --> C["File Scanning & Category Classification"]
    
    C --> D1["Matter.js 2D Physics Engine (Canvas 60 FPS)"]
    C --> D2["Robot Vacuum AI (LiDAR & Patrol Navigation)"]
    C --> D3["Glassmorphism Control Panel (HUD & Modals)"]
    
    D3 --> E1["Plan Preview & Item Exclusion"]
    D3 --> E2["Selection Box Regional Organization"]
    D3 --> E3["Safe Transfer & SHA-256 Verification"]
    
    E3 --> F1["Celebration & Live Stats"]
    E3 --> F2["Single-Click Revert (Undo)"]
    E3 --> F3["HTML / CSV / JSON Report Export"]

Loading

---

Folder & Category Hierarchy

Instead of dumping files into arbitrary buckets, Cleanfy organizes your desktop into an archival-grade structure:

Desktop/
├── 📁 Photos and Images/               (jpg, jpeg, png, webp, gif, bmp, tiff, ico, heic, raw)
├── 📁 Videos/                          (mp4, mkv, mov, avi, webm, wmv, flv, m4v)
├── 📁 Music and Audio/                 (mp3, wav, flac, aac, ogg, m4a, wma)
├── 📁 Documents/
│   ├── 📁 PDF Documents/               (pdf)
│   ├── 📁 Word Documents/              (doc, docx, odt)
│   ├── 📁 Spreadsheets and Data/       (xls, xlsx, csv, ods, tsv)
│   ├── 📁 Text Files/                  (txt, md, rtf, log)
│   └── 📁 Other Documents/             (ppt, pptx, odp, epub, mobi)
├── 📁 Software and Installers/         (exe, msi, msix, bat, cmd, ps1, iso, img)
├── 📁 Compressed Archives/             (zip, rar, 7z, tar, gz, bz2, xz)
├── 📁 Code and Development/
│   ├── 📁 Python Projects/             (py, pyw, ipynb)
│   ├── 📁 Web Projects/                (html, css, js, ts, jsx, tsx, vue, svelte, json)
│   ├── 📁 Java Projects/               (java, jar, class)
│   └── 📁 Other Code Files/            (c, cpp, cs, rs, go, php, rb, sql, sh, yaml)
├── 📁 Design and Graphics/             (psd, ai, blend, svg, xd, fig, sketch, dwg)
├── 📁 Games and Shortcuts/             (Steam, Epic, Riot, Roblox, Minecraft, and game URLs)
├── 📁 Internet Shortcuts/              (url, webloc)
├── 📁 Backup Files/                    (bak, old, backup, dump)
├── 📁 Temporary and Review Files/      (tmp, temp, extensionless files)
└── 📁 Other Files/                     (unclassified miscellaneous extensions)

Note

Categories with zero files never generate empty folders. Existing personal user folders already on your desktop are left untouched.

---

Absolute Safety & Data Integrity Guarantee

1. Zero Deletion APIs: The codebase contains absolutely no deletion operations (fs.unlink, rmdir, trash) and does not send files to the Recycle Bin.
2. SHA-256 Checksum Verification: Hashes are computed both prior to and immediately following file moves; if even 1 byte differs, execution aborts instantly.
3. Overwrite Prevention: If an item with the same name exists in the target folder, it is never overwritten; it is automatically and safely renamed as file (1).ext, file (2).ext.
4. Desktop Directory Boundary (No Path Traversal): File movement is strictly confined to the user's Desktop directory.

---

Quick Start & Installation

Requirements

• Operating System: Windows 10 or Windows 11 (64-bit)
• Node.js: v18+ (Recommended: Node.js 20 or 22 LTS)

1. Clone the Repository

git clone https://github.com/omerfys/Cleanfy.git
cd Cleanfy

2. Install Dependencies

npm install

3. One-Click Launch (Windows)

Double-click start.bat in the repository root to immediately launch the application via its compiled .exe:

start.bat

4. Run in Development Mode (Live Reload)

npm start

5. Package as Windows Executable

npm run package

The packaged output executable is generated under release/win-unpacked/Cleanfy Robot Süpürge.exe.

---

Glassmorphism Control Panel

▲ Draggable minimalist Glassmorphism HUD with Display 1, Display 2, and Display 3 multi-monitor switching

Manage all operations straight from the compact HUD in the top-right corner:

Button / Control	Function
Scan (Tara)	Instantly scans the desktop and imports icons into the physics world.
Start (Başlat)	Starts the safe cleanup routine; the robot navigates to and organizes each file.
Pause / Resume (Duraklat / Devam)	Pauses or resumes the cleaning routine at any second.
Stop (Durdur)	Stops cleanup and switches the robot back to free-roaming mode.
Select Zone & Custom Arrange (Alan Seç & Özel Diz)	Draw an on-screen box to gather specific file types into that zone.
Plan (Plan)	Preview modal allowing individual file review and exclusion.
Report (Rapor)	Detailed report log displaying file movement history and paths.
Undo (Geri Al)	Instantly restores all files moved in the latest cleaning session back to their original spots.

---

Undo & Reporting

▲ Desktop Organization Plan preview, confirmation, and post-operation single-click Undo guarantee

• Session-Based Undo: Once cleanup finishes, a complete session manifest is recorded into memory. Clicking Undo safely moves every displaced file right back to its original desktop coordinates.
• Export Formats:
  • HTML Report: Styled, filterable, and print-ready visual report.
  • CSV Report: Microsoft Excel-ready UTF-8 BOM CSV output with full international character support.
  • JSON Report: Standard structured JSON data for automation scripts and log archiving.

---

Zero Lag & Optimized Physics Engine

• 60 FPS Hardware-Accelerated Canvas: GPU-accelerated smooth rendering loop on HTML5 Canvas 2D.
• Fail-Safe Render Loop: The draw cycle is wrapped in robust try/catch/finally guards so unexpected momentary exceptions never stall the frame pipeline.
• Smart Collision Filtering: Icons settle naturally through floor friction, guided by an obstacle-aware robot pathing algorithm that avoids unnecessary snagging.

---

Frequently Asked Questions (FAQ)

1. Can Cleanfy delete or lose any of my files?

Absolutely not. Cleanfy's source code contains zero file deletion commands. All operations are safe file transfers verified by SHA-256 checksums and can be reversed with a single click.

2. What happens to my existing folders on the desktop?

Existing personal user folders are never modified. Cleanfy only classifies and arranges loose, orphaned files and shortcuts.

3. Does it support OneDrive-synced Desktops?

Yes. Cleanfy automatically detects OneDrive desktop redirects using Windows Registry lookups and specialized PowerShell detection mechanisms.

4. How do I reset a custom area created with Selection Box?

Click the "Reset" button that appears in the top-right menu to release files pinned to the custom zone immediately.

---

SEO Keywords

Cleanfy • Desktop Organizer • Robot Vacuum Simulator • Windows Desktop Cleaner • Matter.js Physics • Electron Desktop App • React 19 • TypeScript • Canvas 2D Simulation • Interactive Vacuum Robot • Selection Box Organizer • Automatic File Organizer • Safe Desktop Cleaner • Omerfy • Creative Coding • Zero Data Loss • Undo Desktop Organization

---

License & Author

This project is open-source under the MIT License.

Developer: @omerfys
GitHub Repository: https://github.com/omerfys/Cleanfy

If you find this project helpful, don't forget to star the repository on GitHub!