mcpField
P
photo-dedup

photo-dedup

github.com/tivojnProductivity056 installsUpdated 37w ago
Repository

About photo-dedup

photo-dedup is a skill for finding duplicate and near-duplicate photos in a folder, then organizing selected images for review. It uses perceptual hashing and keeps originals untouched.

Key features

  1. 01Perceptual-hash image matching
  2. 02Similarity-based photo clustering
  3. 03Largest-file representative selection
  4. 04Browser-based group review
  5. 05Preview mode and threshold control

Use cases

  1. 01Deduplicate event photo folders
  2. 02Review similar shots before saving
  3. 03Find unique images in large collections

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/tivojn/photo-dedup --skill photo-dedup

After installing, type/photo-dedupin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
scripts/
generate_review.py
review_server.py
dedup.py

Details

From the project README

Photo Dedup — Find & Select Unique Photos from Duplicates

Use this skill when the user wants to deduplicate photos, find unique images from a large set, remove similar/duplicate photos, or organize photos by uniqueness. Trigger phrases: "dedup photos", "find duplicate photos", "unique photos", "remove duplicate images", "photo dedup", "/photo-dedup".

Overview

This skill processes a folder of photos (typically hundreds from events like school photography), identifies duplicates and near-duplicates using perceptual hashing, and organizes them into unique vs duplicate folders. It's designed for the workflow where ~500 photos come in but only ~100 are truly unique.

How It Works

  1. Perceptual Hashing — Each image is converted to a perceptual hash (pHash) that represents its visual content. Similar-looking images produce similar hashes, even if they differ in resolution, compression, or minor edits.

  2. Clustering — Images are grouped by hash similarity. Each cluster represents one "scene" or "shot". The best image from each cluster (largest file size = highest quality) is selected as the unique representative.

  3. Output — Unique photos are copied to a unique/ folder. A report is generated showing how many duplicates were found and the cluster groupings.

Usage

Basic — Dedup a folder:
/photo-dedup ~/Photos/school-event/
With custom threshold:
/photo-dedup ~/Photos/school-event/ --threshold 8

Threshold controls similarity sensitivity (default: 6, range 0-20). Lower = stricter matching, higher = more aggressive grouping.

Preview mode (no file copying):
/photo-dedup ~/Photos/school-event/ --preview

Workflow

When the user invokes this skill:

  1. Validate input — Confirm the source folder exists and contains images
  2. Install dependencies if needed — pip3 install Pillow imagehash pillow-heif
  3. Run the dedup scan: 
    python3 ~/.claude/skills/photo-dedup/scripts/dedup.py <source_folder> --preview [--threshold N]
  4. Report results to the user (total, unique, duplicates)
  5. Launch the review server (runs locally, opens browser automatically): 
    python3 ~/.claude/skills/photo-dedup/scripts/review_server.py /tmp/dedup_report_<folder_name>.json --output ~/Desktop/selected_photos &
    The user can then:
    • See all duplicate groups side by side (Notion-style UI)
    • Click to select which photo to keep from each group
    • Use "Auto-select best" for one-click defaults
    • Hit "Save selected" — photos are copied instantly, no Terminal needed
  6. After user saves, tell them where the selected photos are
  7. Kill the server when done: kill $(pgrep -f review_server)

The review server is a lightweight local HTTP server — no install, no config, just Python. Non-technical users only interact with the browser. One click to save.

Output Structure

~/Desktop/selected_photos/     ← User's selected photos (copies, originals untouched)
/tmp/dedup_report_*.json       ← Clustering report
(original photos are NEVER modified or deleted)

Important Notes

  • Non-destructive — Original photos are NEVER moved or deleted. Unique photos are copied to a subfolder.
  • Supported formats — JPG, JPEG, PNG, HEIC, WEBP, TIFF, BMP
  • Performance — Handles 500+ photos in under a minute on modern hardware
  • Selection criteria — When duplicates are found, the largest file (highest quality) is picked as the representative

Comments

Markdown supported