| name | file-organizer |
| description | Organizes files and folders by analyzing content, detecting duplicates, and restructuring directories. Use when the user says: 'organize my files', 'clean up downloads', 'find duplicates', 'restructure folder', 'organize photos', 'desktop cleanup', 'sort files', 'archive old projects', 'folder structure'. Handles Downloads cleanup, duplicate detection, project reorganization, and photo sorting. Do NOT use for code refactoring (use senior-fullstack), git operations, or codebase restructuring within a software project. |
| allowed-tools | ["Read","Write","Bash","Glob","AskUserQuestion"] |
File Organizer
Organize files and folders with analysis, duplicate detection, and automated cleanup.
Workflow
1. Clarify Scope
Before touching any files, confirm with the user:
- Target directory (Downloads, Documents, Projects, etc.)
- Goal (find duplicates, restructure, archive old files)
- Files/folders to exclude (active projects, sensitive data)
- Aggressiveness (conservative sort vs. comprehensive cleanup)
2. Analyze Current State
ls -la [target_directory]
du -sh [target_directory]/* | sort -rh | head -20
Summarize: total files, file type breakdown, size distribution, obvious issues.
3. Detect Duplicates (When Requested)
find [directory] -type f -exec md5 {} \; | sort | uniq -d
For each duplicate set, show:
- All file paths with sizes and modification dates
- Recommendation on which to keep (newest or best-named)
CRITICAL: Always ask for confirmation before deleting any file.
4. Propose Organization Plan
Present the plan as a structured summary before executing:
Current: X files across Y folders, Z GB total
Proposed structure:
[Directory tree]
Changes:
- Create: [new folders]
- Move: [file counts per destination]
- Rename: [patterns]
- Delete: [duplicates/trash, with user approval]
Files needing your decision: [list unclear items]
Wait for explicit approval before proceeding.
5. Execute
mkdir -p "path/to/new/folders"
mv "old/path/file.pdf" "new/path/file.pdf"
Rules:
- Never delete without confirmation
- Log all moves for potential undo
- Preserve original modification dates
- Handle filename conflicts (append suffix, never overwrite)
- Stop and ask if anything unexpected occurs
6. Report Results
After completion, provide:
- Files organized count
- Space freed (if duplicates removed)
- New folder structure tree
- Maintenance tips (weekly sort, monthly archive review)
Common Patterns
| Task | Suggested Structure |
|---|
| Downloads cleanup | Work/, Personal/, Installers/, Archive/, ToSort/ |
| Photo organization | YYYY/MM-MonthName/ (based on EXIF or mtime) |
| Project restructure | Active/, Archive/YYYY/, Templates/ |
| Desktop cleanup | Move everything to Documents/ with proper categorization |
Naming Conventions
- Files:
YYYY-MM-DD-description.ext for dated files
- Folders: lowercase with hyphens (
client-proposals, not Client Proposals)
- Remove download artifacts:
doc-final-v2 (1).pdf to doc.pdf
Error Handling
- If permission denied: inform user which files need elevated permissions
- If disk full during moves: stop, report progress so far, suggest freeing space first
- If filename conflict: append
-1, -2 suffix, never silently overwrite
- If EXIF data unavailable for photos: fall back to file modification date
- If target directory does not exist: create it with
mkdir -p, do not fail silently
