Stream Deck Plugin • User Guide

Downloads Janitor - Folder Cleaner

Monitor clutter, categorize loose files, and safely sweep old installers without opening a file manager. Built for power users, developers, and creators on macOS and Windows by Dloper.

1. Overview & Requirements

Downloads Janitor turns your Stream Deck into an automated organization hub for your Downloads folder. See at a glance how many loose files are occupying your drive, sort them into structured category folders with one tap, and safely relocate bulky older installers and archives to Trash or local storage.

System Requirements:

Operating Systems: macOS 13 or later • Windows 10/11.
Stream Deck Software: Version 6.6 or later.
Hardware Compatibility: Compatible with all Stream Deck models (Stream Deck, MK.2, +, Neo, XL, Mini, Mobile). Janitor Studio requires Stream Deck +.
Folder Access: Ensure Stream Deck has permissions to read and modify files in your user Downloads folder.

2. Action Catalog

Downloads Radar

The Downloads Radar key provides live telemetry and fast triage:

Live Counter: Displays the count and combined gigabytes or megabytes of loose files in your selected directory.
Visual Clutter State: The background and ring transition subtly as file count increases beyond your chosen soft thresholds.
Tap: Instantly opens your Downloads directory in Finder (macOS) or File Explorer (Windows).
Hold (1.5 seconds): Triggers an automated sweep of eligible older installers (such as .dmg, .pkg, .exe, and .msi), freeing disk space immediately.

Smart Organize

The Smart Organize action sorts loose files into organized categories with a single keypress:

Documents: .pdf, .docx, .xlsx, .pptx, .txt, .csv, .md, etc.
Images: .png, .jpg, .jpeg, .svg, .gif, .webp, .heic, etc.
Installers: .dmg, .pkg, .exe, .msi, .deb, .rpm, etc.
Archives: .zip, .tar, .gz, .7z, .rar, etc.
Media: .mp4, .mov, .mp3, .wav, .m4a, etc.
Code: .js, .ts, .json, .py, .html, .css, etc.

Preserved Directory Structure: Existing subfolders, git repositories, and unorganized custom folders are intentionally skipped and preserved in place.

Janitor Studio (Stream Deck +)

For Stream Deck + users, Janitor Studio provides granular category cleaning from rotary encoders:

Rotate: Turn the dial to step through cleanup candidate filters (e.g., Old Installers, Large Archives, Screenshots, Old Media).
Touchstrip Display: Shows candidate file count, total size to reclaim, and destination settings.
Push or Tap: Push the dial encoder or tap the touchstrip to confirm moving matching files to your designated Trash or Archive target.

3. Safety Principles & Guardrails

Zero Permanent Deletions: Downloads Janitor never runs destructive permanent delete commands (like rm -rf). All cleanup operations relocate files either to your operating system's native Trash / Recycle Bin or into a local archive subfolder, ensuring full recovery if needed.

In-Progress Download Protection

Active web downloads are automatically detected and protected. Any files bearing partial download extensions—including .crdownload (Chrome, Brave, Edge), .download (Safari), and .part (Firefox)—are strictly excluded from organization and sweep routines.

Custom Age Thresholds

Avoid touching files you are currently using. In the Property Inspector, choose the minimum age before files become eligible for installer sweeping:

3 Days: Ideal for fast-moving environments and tight SSD storage budgets.
7 Days (Default): The sweet spot for weekly workflow decluttering.
14 Days / 30 Days: Conservative settings for projects where installer setups must remain handy.

4. Destination Configurations: Trash vs. Archive

Destination Mode	Operating Behavior	Disk Recovery
System Trash (Default)	Moves files directly to macOS Trash or Windows Recycle Bin.	Space is reclaimed when you empty your system Trash. Full restore supported via OS contextual menus.
Local Archive Folder	Moves files into a dedicated subfolder (e.g. `Downloads/Janitor_Archive`).	Keeps files accessible on disk without cluttering the root Downloads view. Zero risk of automatic trash purging.

5. Troubleshooting & FAQs

macOS Folder Permissions

If Downloads Janitor reports an error accessing files, verify that Stream Deck has permission to manage files in the Downloads folder:

Open System Settings > Privacy & Security > Files and Folders.
Scroll to Stream Deck and ensure the Downloads Folder switch is toggled ON.

Disk Space Did Not Increase Immediately

When using the default System Trash destination, moved files reside in your macOS Trash or Windows Recycle Bin. Until the Trash is emptied, the operating system still allocates those blocks on your drive.

Custom Folder Monitoring

You can point Downloads Janitor to any folder on your computer—not just the system default Downloads folder. In the Property Inspector, enter a custom path (e.g., a shared desktop intake folder, a screen capture directory, or an external drive landing folder).

Need assistance?
Visit our Stream Deck Support Hub or contact our developer support team.