Folder Cleaner

A smart folder cleaner that detects and helps manage sensitive files on Unix-like systems.

Note: Built with AI assistance! 🎉

• Human author had the idea, designed it, AI coded it, human reviewed it all
• Built way faster than if the human did it alone!
• Built way smarter than if the AI did it alone!
• The AI stayed in its lane and didn't take over control - we are safe & sound

Features

• 🔍 Smart File Detection: Automatically identifies sensitive files based on extensions, patterns, and content
• 🎯 Category-Based System: Predefined categories for different types of sensitive files (security, financial, personal, etc.)
• 🖥️ Interactive Interface: Rich terminal UI with keyboard navigation and visual selection
• 📁 Multi-Folder Support: Monitor and clean multiple directories simultaneously
• ⚙️ Flexible Configuration: Customizable patterns and categories through interactive setup
• 🛡️ Safe Operations: Dry-run mode to preview changes before deletion
• 💾 Configuration Persistence: Saves your preferences for future use

Installation

From Source

git clone https://github.com/aragaoi/folder-cleaner.git
cd folder-cleaner
pip install -e .

Direct Installation

pip install git+https://github.com/aragaoi/folder-cleaner.git

Quick Start

First Time Setup

folder-cleaner --setup

This will guide you through:

• Selecting which categories of files to monitor
• Configuring which folders to scan
• Setting up custom patterns

Basic Usage

# Interactive mode (recommended)
folder-cleaner

# Dry-run mode (preview without deleting)
folder-cleaner --dry-run

# Auto-delete mode (use with caution)
folder-cleaner --auto-delete

# Custom folder
folder-cleaner --folder ~/Downloads

Available Categories

• Security & Authentication: Private keys, certificates, tokens
• Environment & Configuration: .env files, config files, settings
• Log Files: Log files that might contain sensitive information
• Database Files: Database exports, SQL files, data dumps
• Sensitive Documents: Resumes, contracts, personal documents
• Financial Documents: Bank statements, payment info, tax documents
• Archive Files: Compressed files with sensitive content
• Executable Files: Installers and executable files
• Configuration Files: JSON, XML, YAML configuration files

Configuration

The tool creates a configuration file at ~/.folder_cleaner_config.json that stores:

• Selected sensitive file categories
• Monitored folders
• Custom patterns for each category
• User preferences

Managing Patterns

# View current patterns
folder-cleaner --show-patterns

# Edit patterns interactively
folder-cleaner --edit-patterns

# Show configured categories
folder-cleaner --show-categories

Operation Modes

Interactive Mode (Default)

• Scans folders for sensitive files
• Displays files with details (size, modification date, location)
• Interactive selection of files to delete
• Confirmation before deletion

Dry-Run Mode

• Shows what would be deleted without actually deleting
• Perfect for testing and verification
• Safe to run multiple times

Auto-Delete Mode

• Automatically deletes all detected sensitive files
• Use with extreme caution
• No confirmation prompts

Scheduled Mode

• Run cleaning operations automatically at specified intervals
• Support for daily, weekly, hourly, and custom intervals
• Can run in background as daemon process
• Option to enable auto-delete for scheduled runs

Examples

Clean Downloads Folder

folder-cleaner --folder ~/Downloads

Preview Changes in Multiple Folders

folder-cleaner --dry-run

Custom Configuration File

folder-cleaner --config ~/custom_config.json

Scheduled Cleaning

# Daily cleaning at 9 AM
folder-cleaner --schedule daily --time "09:00"

# Weekly cleaning every Monday at 10 AM
folder-cleaner --schedule weekly --time "10:00"

# Hourly cleaning
folder-cleaner --schedule hourly

# Custom interval (every 30 minutes)
folder-cleaner --schedule custom --interval 30

# Run as daemon with auto-delete
folder-cleaner --schedule daily --time "08:00" --auto-schedule --daemon

Safety Features

• Dry-run by default: Always preview before deletion
• File information display: See size, date, and location before deciding
• Interactive selection: Choose exactly which files to delete
• Confirmation prompts: Multiple safety checks before deletion
• Configuration backup: Your settings are automatically saved

Requirements

• Python 3.6+
• Unix-like operating system (macOS, Linux)
• Terminal with support for ANSI colors

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

1. Check the help: folder-cleaner --help
2. Review the configuration: folder-cleaner --show-categories
3. Open an issue on GitHub

Version History

• 1.0.0: Initial stable release with all core features
• 0.2.0: Enhanced interactive selection and project refactoring
• 0.1.0: Basic functionality and modular architecture

---

⚠️ Warning: This tool can permanently delete files. Always use dry-run mode first and review the files before deletion.