SmartFolder - Intelligent File Organizer

Automatically organize, analyze, and clean up your file system using natural language commands.

When to Use

✅ Use this skill when:

• "Organize my downloads folder"
• "Clean up duplicate files"
• "Find large files taking up space"
• "Sort files by date/project/type"
• "Rename photos based on date taken"
• "Analyze disk usage"
• "Archive old files"
• "Move documents to appropriate folders"

❌ Don't use when:

• File operations requiring elevated permissions (use system tools)
• Network/cloud storage operations (not supported yet)
• Real-time sync needs (use dedicated sync tools)

Features

1. Intelligent Organization

• Auto-categorize files by type (Documents, Images, Videos, Archives, etc.)
• Sort by date, size, or custom rules
• Smart project detection (groups related files)

2. Duplicate Detection

• Hash-based duplicate detection
• Similar image detection (perceptual hashing)
• Safe preview before deletion

3. Bulk Renaming

• Date-based renaming for photos/videos
• Sequential numbering
• Pattern-based replacement

4. Disk Analysis

• Visual disk usage report
• Find space hogs
• Identify old/unused files

5. Archive & Cleanup

• Compress old files
• Move to archive folders
• Empty trash/recycle bin

Quick Start

Check installation

python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py --version

Basic usage

# Organize Downloads folder
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py organize ~/Downloads

# Find duplicates
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py duplicates ~/Documents

# Analyze disk usage
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py analyze ~/

Commands

organize

Organize files in a directory.

python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py organize <path> [options]

Options:
  --by-type          Organize by file type (default)
  --by-date          Organize by modification date
  --by-size          Organize by size ranges
  --dry-run          Preview changes without executing
  --target-dir       Custom target directory

duplicates

Find and manage duplicate files.

python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py duplicates <path> [options]

Options:
  --delete           Delete duplicates (prompts for confirmation)
  --move-to          Move duplicates to specified folder
  --similar-images   Include visually similar images

analyze

Analyze disk usage.

python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py analyze <path> [options]

Options:
  --top N            Show top N largest files (default: 20)
  --older-than DAYS  Find files older than N days
  --output-format    json, table, or chart

rename

Bulk rename files.

python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py rename <path> [options]

Options:
  --by-date-taken    Rename photos by EXIF date
  --pattern          Pattern for renaming
  --sequential       Add sequential numbers

Examples

Example 1: Organize Downloads

# Preview changes first
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py organize ~/Downloads --dry-run

# Execute organization
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py organize ~/Downloads

Result:

Downloads/
├── Documents/
│   ├── report.pdf
│   └── invoice.docx
├── Images/
│   ├── screenshot.png
│   └── photo.jpg
├── Archives/
│   └── backup.zip
└── Misc/
    └── readme.txt

Example 2: Clean up duplicates

# Find duplicates in Documents
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py duplicates ~/Documents

# Move duplicates to review folder
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py duplicates ~/Documents --move-to ~/Duplicates_Review

Example 3: Disk space analysis

# Find what's taking space
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py analyze ~/ --top 10

Output:

Top 10 Largest Files:
1. ~/Videos/project.mp4        2.3 GB
2. ~/Downloads/backup.zip      1.1 GB
3. ~/Documents/archive.pst     890 MB
...

Safety Features

• ✅ Dry-run mode - Preview all changes before executing
• ✅ Confirmation prompts - For destructive operations
• ✅ Trash support - Deleted files go to system trash (not permanently deleted)
• ✅ Undo log - Operations are logged for potential undo
• ✅ Skip system files - Never touches hidden/system files

Configuration

Create ~/.smartfolder/config.json for default settings:

{
  "default_organization": "by-type",
  "categories": {
    "Documents": [".pdf", ".doc", ".docx", ".txt", ".md"],
    "Images": [".jpg", ".jpeg", ".png", ".gif", ".bmp"],
    "Videos": [".mp4", ".avi", ".mov", ".mkv"],
    "Audio": [".mp3", ".wav", ".flac", ".aac"],
    "Archives": [".zip", ".rar", ".7z", ".tar.gz"],
    "Code": [".py", ".js", ".html", ".css", ".json"]
  },
  "duplicate_check": {
    "min_size": 1024,
    "skip_hidden": true
  }
}

Requirements

• Python 3.8+
• Optional: ffmpeg (for media metadata)

Installation

# Install dependencies
pip install -r ~/.openclaw/workspace/smartfolder/requirements.txt

# Verify installation
python3 ~/.openclaw/workspace/smartfolder/scripts/smartfolder.py --version

Troubleshooting

Permission errors

Run with appropriate permissions for the target directory.

Large directories

For directories with 10,000+ files, use --batch-size option.

Special characters

Files with special characters are handled safely with proper escaping.

License

MIT License - See LICENSE file

Contributing

Contributions welcome! Please submit issues and PRs to the GitHub repository.