screenshot-organizer

OCR, tag, search, deduplicate, and organize screenshots. Makes screenshots searchable by content, detects and removes duplicates, groups by topic, and generates a searchable index. Use when a user has hundreds of unorganized screenshots and needs to find, clean, or categorize them.

Overview

Screenshots accumulate fast — error reports, memes, recipes, payment confirmations, chat conversations — and they pile up in a single folder with useless filenames like Screenshot_2026-08-13-094231.png. This skill uses image hashing for deduplication, OCR text extraction to make screenshots searchable, content-based tagging to categorize them, and folder organization to sort them by topic. Turn a folder of 500 anonymous images into a searchable, categorized library.

When to Use

• A user has hundreds of screenshots and needs to find a specific one
• A user wants to delete duplicates and reclaim storage space
• A user needs to search screenshots by text content ("find the screenshot with the confirmation number")
• A user wants screenshots organized into folders by category
• A user is running out of storage due to screenshot accumulation
• Don't use for: organizing photos from a camera (different workflow), or live screen capture automation

Core Features

1. Deduplication Engine (scripts/dedup_scanner.py)

Finds exact and near-duplicate screenshots using perceptual hashing:

• Exact duplicates: identical files (same MD5 hash)
• Near-duplicates: visually similar (same screenshot taken twice, minor cropping differences)
• Generates a deletion plan with confidence scores

2. OCR Text Extractor (scripts/ocr_extractor.py)

Extracts text from screenshots using Tesseract OCR:

• Identifies text content for searchability
• Detects URLs, email addresses, phone numbers, dates
• Generates a searchable text index
• Tags screenshots by content keywords

3. Organizer (scripts/screenshot_organizer.py)

The main orchestrator that:

• Scans a directory for screenshots
• Runs dedup analysis
• Runs OCR extraction
• Categorizes by content
• Proposes folder organization
• Generates a searchable index

Numbered Workflow

1. Scan — Identify all screenshot files in the target directory
2. Deduplicate — Find exact and near-duplicates, flag for deletion
3. Extract text — Run OCR on each unique screenshot
4. Categorize — Classify by detected content (receipt, chat, error, meme, code, etc.)
5. Organize — Propose folder structure and move/rename files
6. Index — Generate a searchable JSON index of all screenshots

Common Pitfalls

1. Deleting near-duplicates without review. A "near-duplicate" might be a cropped version with different content. Always review before deleting.

2. OCR quality varies by screenshot resolution. Low-resolution or small-text screenshots may have poor OCR results. Check confidence scores.

3. Filename patterns vary by platform. macOS uses Screenshot 2026-01-01 at 10.00.00.png, Android uses Screenshot_20260101_100000.png, Windows uses Screenshot (1).png. The scanner detects all patterns.

4. Large collections take time. OCR on 500+ images can take 10-30 minutes. The tool processes in batches and can resume.

5. Privacy concern with OCR. Screenshots may contain passwords, private messages, financial info. The extracted text index is stored locally and should be treated as sensitive.

Verification Checklist

• All screenshot files detected and counted
• Exact duplicates identified and flagged
• Near-duplicates identified with confidence scores
• OCR text extracted for all unique images
• Content categories assigned
• Searchable index generated
• Folder organization plan reviewed before executing moves

Example Session

User: "I have 847 screenshots in my Pictures folder and I can never find anything. Help me organize them."

Agent:

text

📊 SCREENSHOT ORGANIZATION REPORT
═══════════════════════════════════════
Total screenshots scanned: 847

DEDUPLICATION:
  Exact duplicates: 43 (saving ~127 MB)
  Near-duplicates: 28 pairs (flagged for review)
  Total reclaimable: ~340 MB

CONTENT CATEGORIES:
  💬 Chat/Social: 234 (28%)
  🧾 Receipt/Payment: 156 (18%)
  🐛 Error/Bug Report: 89 (11%)
  📄 Document/Text: 78 (9%)
  🎭 Meme/Image: 67 (8%)
  💻 Code/Technical: 54 (6%)
  🗺️ Map/Location: 43 (5%)
  📱 App Screenshot: 38 (4%)
  ❓ Unclassified: 88 (10%)

SEARCH INDEX:
  804 unique images indexed
  12,456 words extracted via OCR
  89 URLs detected
  34 email addresses found
  23 phone numbers found

⏱️ ESTIMATED TIME: 15 minutes to organize