| name | apple-photos-cleaner |
| description | Analyze, clean up, and organize Apple Photos libraries. Find and report junk photos (screenshots, low-quality, burst leftovers, duplicates), analyze storage usage, generate photo timeline recaps, plan smart exports, analyze Live Photos, check iCloud sync, audit shared libraries, detect similar photos, curate seasonal highlights, and score face quality. All analysis operations are READ-ONLY on the database (safe). macOS only. Requires Python 3.9+ (stdlib only) and access to the Apple Photos SQLite database. Trigger on: Photos cleanup, photo storage, duplicate photos, junk photos, screenshot cleanup, Photos analysis, photo timeline, photo export, Photos library stats, burst cleanup, storage hogs, photo organization, Live Photos, iCloud sync, shared library, similar photos, seasonal highlights, face quality, portraits. |
Apple Photos Cleaner
Comprehensive toolkit for analyzing and cleaning up Apple Photos libraries. Goes beyond what Photos.app offers: intelligent junk detection, detailed storage analysis, duplicate finding with quality scoring, timeline recaps for storytelling, and smart export planning.
Overview
Apple Photos is great at organizing and syncing photos, but it's not so great at cleanup. This skill fills that gap:
- Library Analysis — Get the big picture: counts, storage, date ranges, people, quality distribution
- Junk Finder — Identify screenshots, low-quality photos, burst leftovers, old screenshots
- Duplicate Finder — Find duplicates using Apple's detection + timestamp/dimension matching
- Storage Analyzer — Detailed breakdown by year, type, file format, growth trends, storage hogs
- Timeline Recap — Generate narrative summaries of photo activity for any date range
- Smart Export — Plan organized exports by year/month, person, album, or location; AppleScript export
- Best Photos / Hidden Gems — Surface high-quality photos you haven't favorited
- People Analyzer — Deep analysis of people: co-occurrence, trends over time, best photos per person
- Location Mapper — Cluster GPS coordinates into locations, identify trips, offline reverse geocoding
- Scene Search — Search by ML-detected content (beach, dog, food) or generate content inventory
- Photo Habits — Behavioral analytics: time-of-day, day-of-week, streaks, seasonal trends
- On This Day — See what you photographed on today's date in prior years
- Album Auditor — Find orphan photos, empty albums, overlap between albums
- Cleanup Executor — Batch move junk to trash via AppleScript with confirmation
- Live Photo Analyzer — Compare Live Photos vs stills, find conversion candidates, storage impact
- Shared Library — Analyze Shared Library vs personal: contributors, content splits, storage
- iCloud Status — Check iCloud sync coverage: synced vs local-only, large unsynced items
- Similarity Finder — Detect visually similar photos using computed quality feature vectors
- Seasonal Highlights — Curate the best photos per season using quality scores and favorites
- Face Quality Scoring — Rank face photos per person: find best/worst portraits
Safety: All operations are READ-ONLY database queries. No photos are modified or deleted without explicit user action.
When to Use This Skill
Use when users mention:
- Cleaning up Photos / freeing up photo storage
- Finding duplicate photos
- Removing old screenshots
- Analyzing Photos library storage
- Finding junk or low-quality photos
- Organizing photo exports
- Getting photo timeline summaries ("what did I do last week?")
- Burst photo cleanup
- Finding storage hogs in Photos
- Finding best or hidden gem photos
- People in photos, who appears together
- Where photos were taken, travel, trips, locations
- Searching photos by content (beach, sunset, dog, food)
- Photo-taking habits, patterns, streaks
- "On this day" / photo memories from past years
- Album organization, orphan photos, album cleanup
- Actually deleting junk photos (batch cleanup)
- Live Photos analysis, converting Live Photos to stills
- Shared Library content, who contributed what
- iCloud sync status, unsynced photos, cloud coverage
- Finding similar-looking photos
- Seasonal photo highlights, best of each season
- Face/portrait quality, best/worst portraits per person
Quick Start
All scripts work standalone. The Photos database is automatically located at:
~/Pictures/Photos Library.photoslibrary/database/Photos.sqlite
Basic workflow:
- Run
library_analysis.py to get overview
- Run
junk_finder.py to identify cleanup candidates
- Run
duplicate_finder.py to find duplicates
- Use results to guide manual cleanup in Photos.app
Commands
1. Library Analysis
Get comprehensive library statistics: counts, storage, date ranges, people, quality scores.
python3 scripts/library_analysis.py [--human] [--output FILE]
Options:
--human — Human-readable summary instead of JSON--output FILE — Write JSON to file--db-path PATH — Custom database path--library PATH — Custom Photos library path
Example Output:
📊 APPLE PHOTOS LIBRARY ANALYSIS
==================================================
Total Assets: 12,453
Total Storage: 48.3 GB
Average Size: 4.1 MB
Date Range: 2020-01-15 to 2025-03-03
By Type:
Photo: 11,234
Video: 891
Screenshots: 328
Favorites: 456
Bursts: 1,234
By Year:
2025: 1,203 items, 5.2 GB
2024: 3,456 items, 15.1 GB
2023: 2,987 items, 12.4 GB
...
Top People:
Jonah: 3,456 photos
Silas: 3,234 photos
...
Usage in Conversation:
User: "How many photos do I have?"
AI: Runs library_analysis.py with --human flag, reports summary
User: "Show me my Photos storage breakdown"
AI: Runs library_analysis.py, highlights key stats
2. Junk Finder
Identify cleanup candidates: screenshots, low-quality photos, burst leftovers, duplicates.
python3 scripts/junk_finder.py [--screenshot-age DAYS] [--quality-threshold N] [--human]
Options:
--screenshot-age DAYS — Consider screenshots older than N days as junk (default: 30)--quality-threshold N — Quality score threshold for low-quality (default: 0.3, range: 0.0-1.0)--no-duplicates — Skip duplicate detection--human — Human-readable summary--output FILE — Write JSON to file
Example Output:
🗑️ JUNK FINDER RESULTS
==================================================
Found:
📸 Screenshots: 328
└─ Old (>30 days): 287
📉 Low Quality: 156
📸 Burst Leftovers: 1,089
👥 Possible Duplicates: 45
Estimated Savings:
Conservative: 2.3 GB
(Old screenshots + burst leftovers)
Aggressive: 5.7 GB
(All screenshots + low quality + bursts + ~50% of duplicates)
What It Finds:
- Screenshots — Detected via
ZISDETECTEDSCREENSHOT flag
- Old screenshots — Screenshots older than specified age (safe to delete)
- Low quality — Photos with low quality scores (high failure/noise, low composition/lighting)
- Burst leftovers — Unpicked photos from burst sequences
- Possible duplicates — Using Apple's built-in detection
Usage in Conversation:
User: "Find junk in my Photos"
AI: Runs junk_finder.py, reports totals and estimated savings
User: "How many old screenshots do I have?"
AI: Runs junk_finder.py, focuses on screenshot stats
User: "What can I delete to free up 5GB?"
AI: Runs junk_finder.py, shows conservative/aggressive estimates, suggests next steps
3. Duplicate Finder
Find duplicate photos and recommend which to keep based on quality, favorite status, and file size.
python3 scripts/duplicate_finder.py [--human] [--output FILE]
Detection Methods:
- Apple's built-in — Uses
ZDUPLICATEASSETVISIBILITYSTATE
- Timestamp + dimensions — Photos taken at same second with same dimensions
Recommendation Logic:
- Favorites get priority
- Screenshots get penalty
- Highest quality score preferred
- Largest file size as tiebreaker
Example Output:
👥 DUPLICATE FINDER RESULTS
==================================================
Found 12 duplicate groups
Total duplicates: 27
Can safely delete: 15
Total size: 156 MB
Potential savings: 89 MB
Sample groups (showing first 5):
Group 1 (apple_builtin):
✓ KEEP ★ IMG_1234.jpg (4.2 MB, Q:0.823)
DELETE IMG_1234-2.jpg (4.1 MB, Q:0.801)
Group 2 (timestamp_dimensions):
✓ KEEP IMG_5678.heic (2.8 MB, Q:0.756)
DELETE IMG_5678-edited.jpg (3.1 MB, Q:0.654)
Usage in Conversation:
User: "Do I have duplicate photos?"
AI: Runs duplicate_finder.py, reports findings
User: "Find duplicates and tell me which to delete"
AI: Runs duplicate_finder.py, explains recommendations
4. Storage Analyzer
Detailed storage breakdown: by year, type, source, growth trends, file types, storage hogs.
python3 scripts/storage_analyzer.py [--human] [--output FILE]
Analyzes:
- Total storage and breakdown by photo/video
- Storage by year and month
- Screenshots vs regular photos
- File types (JPEG, HEIC, MOV, etc.)
- Growth trends over time
- Top 20 largest files
Example Output:
💾 STORAGE ANALYSIS
==================================================
Total Storage: 48.3 GB
By Type:
Photo: 32.1 GB (66.5%)
11,234 items, avg 2.9 MB
Video: 16.2 GB (33.5%)
891 items, avg 18.7 MB
By Source:
Photos & Videos: 46.1 GB (95.4%)
Screenshots: 2.2 GB (4.6%)
By Year:
2025: 5.2 GB (1,203 items)
2024: 15.1 GB (3,456 items)
2023: 12.4 GB (2,987 items)
...
Top 10 Largest Files:
1. 📹 287 MB - VID_2024_vacation.mov
2. 📹 245 MB - VID_2024_swim_meet.mov
3. 📹 198 MB - VID_2023_birthday.mov
...
Recent Growth (last 12 months):
Total added: 18.7 GB
Average per month: 1.6 GB
Usage in Conversation:
User: "What's taking up space in my Photos?"
AI: Runs storage_analyzer.py, highlights biggest categories
User: "Show me my largest videos"
AI: Runs storage_analyzer.py, focuses on storage_hogs section filtered by videos
User: "How much storage am I adding per month?"
AI: Runs storage_analyzer.py, reports recent growth stats
5. Timeline Recap
Generate narrative summaries of photo activity for any date range. Groups photos into events and includes context: people, locations, scenes.
python3 scripts/timeline_recap.py --start-date YYYY-MM-DD [--end-date YYYY-MM-DD] [--narrative]
Options:
--start-date — Start date (required)--end-date — End date (optional, defaults to today)--cluster-hours N — Hours between photos to consider separate events (default: 4)--narrative — Output narrative text instead of JSON--output FILE — Write to file
What It Generates:
- Day-by-day photo activity
- Event clustering (groups photos taken close together)
- People detected in each event
- Scene classifications (beach, sunset, dog, etc.)
- Location data (if available)
- Favorites count
Example Output:
📅 PHOTO TIMELINE RECAP
==================================================
Period: 2025-03-01 to 2025-03-07
Total: 156 photos across 5 days
Events: 12
📆 2025-03-01 (Saturday) - 45 photos
🕐 09:15 (2h 15m)
32 photos, 2 videos ⭐ 5 favorites
👥 Jonah, Silas
🏷️ swimming, pool, sports
📍 41.5369, -90.5776
🕐 18:30 (45m)
13 photos
👥 Jonah, Silas
🏷️ dinner, food, family
Usage in Conversation:
User: "What did I do last week?"
AI: Runs timeline_recap.py with last week's dates, narrates the timeline in story form
User: "Show me my photo activity for February"
AI: Runs timeline_recap.py with Feb 1 - Feb 28, summarizes highlights
User: "Tell me about our vacation photos from August"
AI: Runs timeline_recap.py with August dates, creates a narrative story
AI Tip: When presenting timeline results, narrate them like a story! Don't just dump the JSON. Example:
"You had a busy Saturday on March 1st! In the morning around 9:15, you spent about 2 hours at the pool — 32 photos with Jonah and Silas, mostly swimming and sports shots. You marked 5 as favorites. Then in the evening around 6:30, you captured a family dinner with 13 photos. Looks like a great day!"
6. Smart Export
Plan organized exports by year/month, person, album, or location. Shows what will be exported without actually doing it (unless confirmed).
python3 scripts/smart_export.py --output-dir PATH [--organize-by MODE] [--plan-only]
Options:
--output-dir PATH — Where to export (required)--organize-by MODE — How to organize: year_month, person, album, location (default: year_month)--favorites — Export only favorites--start-date YYYY-MM-DD — Filter by start date--end-date YYYY-MM-DD — Filter by end date--person NAME — Export only photos with this person--album NAME — Export only from this album--plan-only — Show plan without exporting (recommended first step)
Example Output:
📤 EXPORT PLAN
==================================================
Organization: year_month
Total photos: 3,456
Total size: 15.2 GB
Folders: 36
Folders:
2025/01-January/
123 items, 542 MB
2025/02-February/
156 items, 687 MB
2025/03-March/
89 items, 398 MB
...
Note: Actual export via AppleScript is not fully implemented. This command generates the export plan and folder structure. For now, use this to identify what to export, then do it manually in Photos.app.
Usage in Conversation:
User: "I want to export all my 2024 photos organized by month"
AI: Runs smart_export.py with year filter and --plan-only, shows the plan
User: "Export all photos with Jonah"
AI: Runs smart_export.py with --person "Jonah" and --plan-only, shows what would be exported
7. Best Photos / Hidden Gems
Surface your highest-quality photos using Apple's computed quality scores. Find hidden gems — great photos you never favorited.
python3 scripts/best_photos.py [--min-quality N] [--top N] [--hidden-gems] [--human]
Options:
--min-quality N — Minimum quality score threshold (default: 0.7, range: 0.0-1.0)--top N — Number of top photos to return (default: 50)--hidden-gems — Only show photos that are NOT favorited--year YYYY — Filter to specific year--human — Human-readable summary--output FILE — Write JSON to file
What It Shows:
- Quality score distribution across your library (excellent/good/average/poor)
- Top N photos ranked by quality with detailed score breakdowns
- Hidden gems: high-quality photos you haven't favorited yet
- Per-photo scores for composition, lighting, symmetry, patterns, etc.
Example Output:
⭐ BEST PHOTOS / HIDDEN GEMS
==================================================
Photos with quality scores: 11,234
Above threshold (0.7): 2,456
Hidden gems (great but not favorited): 2,100
Already favorited high-quality: 356
Quality Distribution:
🌟 Excellent (≥0.85): 456
✅ Good (≥0.70): 2,000
📊 Average (≥0.50): 5,234
📉 Below avg (≥0.30): 2,544
❌ Poor (<0.30): 1,000
Top 20 Photos:
1. IMG_1234.jpg
Q:0.952 | 4.2 MB | 4032x3024 💎
📐 composition:0.95, lighting:0.92, symmetry:0.88
Usage in Conversation:
User: "Show me my best photos"
AI: Runs best_photos.py with --human flag, highlights top shots
User: "Find hidden gems I haven't favorited"
AI: Runs best_photos.py with --hidden-gems, suggests which to favorite
User: "What are my best photos from 2025?"
AI: Runs best_photos.py with --year 2025, shows quality distribution and top picks
8. People Analyzer
Deep analysis of people detected in your photos: who appears most, who's photographed together, trends over time, best photo of each person.
python3 scripts/people_analyzer.py [--min-photos N] [--top N] [--human]
Options:
--min-photos N — Minimum photos to include a person (default: 5)--top N — Number of top people to analyze in detail (default: 20)--human — Human-readable summary--output FILE — Write JSON to file
What It Shows:
- All named people ranked by photo count
- Per-person yearly trends (are you photographing them more or less?)
- Co-occurrence analysis (who appears together most)
- Best quality photo for each person
- Favorites count per person
- Unnamed face count
Example Output:
👥 PEOPLE ANALYZER
==================================================
Named people (≥5 photos): 15
Photos with unnamed faces: 1,234
Top People:
Jonah: 3,456 photos (★ 89)
📅 2023:890, 2024:1,200, 2025:1,366
Silas: 3,234 photos (★ 76)
📅 2023:845, 2024:1,100, 2025:1,289
Frequently Photographed Together:
Jonah + Silas: 2,100 photos
Jonah + Mom: 456 photos
Usage in Conversation:
User: "Who's in my photos the most?"
AI: Runs people_analyzer.py, reports top people with counts
User: "Who do I photograph together?"
AI: Runs people_analyzer.py, focuses on co-occurrence analysis
9. Location / Travel Mapper
Analyze where your photos were taken. Clusters GPS coordinates into locations, identifies trips, and shows most-photographed places.
python3 scripts/location_mapper.py [--radius N] [--year YYYY] [--human]
Options:
--radius N — Cluster radius in km (default: 1.0)--year YYYY — Filter to specific year--min-photos N — Minimum photos per location cluster (default: 3)--human — Human-readable summary--output FILE — Write JSON to file
What It Shows:
- GPS coverage percentage
- Location clusters with photo counts, date ranges, and people
- Identified trips (clusters with 5+ photos spanning 4+ hours)
- Per-location monthly breakdown
Example Output:
📍 LOCATION / TRAVEL MAPPER
==================================================
Photos with GPS: 8,456 (67.9%)
Without GPS: 3,997
Unique locations: 45
Possible trips: 12
Top Locations:
1. (41.5369, -90.5776)
1,234 photos ⭐12 🧳 | 5.2 GB
📅 2020-01-15 → 2025-03-03
👥 Jonah, Silas
Usage in Conversation:
User: "Where have I taken the most photos?"
AI: Runs location_mapper.py, reports top locations
User: "Show me my trips from 2025"
AI: Runs location_mapper.py with --year 2025, highlights identified trips
10. Scene / Content Search
Search photos by ML-detected scene classifications (beach, sunset, dog, food, etc.) or generate a complete content inventory.
python3 scripts/scene_search.py [--search TERM] [--min-confidence N] [--human]
Options:
--search TERM — Scene name to search for (omit for content inventory)--min-confidence N — Minimum confidence score (default: 0.0)--top N — Number of search results (default: 50)--year YYYY — Filter to specific year--human — Human-readable summary--output FILE — Write JSON to file
Modes:
- Search mode (
--search beach) — Find all photos matching a scene label
- Inventory mode (no --search) — Show all scene labels with counts, grouped by category
Example Output (inventory):
🏷️ SCENE / CONTENT SEARCH
==================================================
Unique scene labels: 234
Scene-tagged entries: 45,678
Library total: 12,453
By Category:
📂 Nature Outdoor (5,678 photos)
beach: 234
sunset: 189
mountain: 156
📂 Animals (2,345 photos)
dog: 1,234
cat: 567
📂 Food Drink (1,890 photos)
food: 890
coffee: 234
Usage in Conversation:
User: "How many beach photos do I have?"
AI: Runs scene_search.py --search beach, reports count and related scenes
User: "What kinds of photos do I take?"
AI: Runs scene_search.py (inventory mode), summarizes categories
11. Photo Habits & Insights
Behavioral analytics: when you shoot most, busiest days, seasonal patterns, streaks, photo vs video ratio trends.
python3 scripts/photo_habits.py [--year YYYY] [--human]
Options:
--year YYYY — Filter to specific year--human — Human-readable summary--output FILE — Write JSON to file
What It Shows:
- Time-of-day breakdown (morning/afternoon/evening/night)
- Peak hour, peak day of week, peak month
- Day-of-week distribution with visual bars
- Longest photo streak (consecutive days with photos)
- Busiest single day
- Year-over-year trends with video ratio
- Monthly trend with photos/videos/screenshots breakdown
Example Output:
📊 PHOTO HABITS & INSIGHTS
==================================================
Total: 11,234 photos, 891 videos, 328 screenshots
Average per active day: 8.3
⏰ When You Shoot:
Peak hour: 14:00
Peak day: Saturday
Peak month: Jul
Time of Day:
Morning (6am-12pm): 3,456 (28.1%) █████████
Afternoon (12pm-6pm): 5,123 (41.6%) █████████████
Evening (6pm-12am): 2,987 (24.3%) ████████
Night (12am-6am): 737 (6.0%) ██
🔥 Streaks:
Longest streak: 45 consecutive days
(2024-06-15 → 2024-07-29)
Usage in Conversation:
User: "What are my photo-taking patterns?"
AI: Runs photo_habits.py, narrates key insights
User: "When do I take the most photos?"
AI: Runs photo_habits.py, highlights peak times and days
12. On This Day / Memory Lane
See what you photographed on today's date in previous years. Includes people, scenes, and quality context.
python3 scripts/on_this_day.py [--date YYYY-MM-DD] [--window N] [--human]
Options:
--date YYYY-MM-DD — Target date (defaults to today)--window N — Include photos ±N days around target (default: 0)--human — Human-readable summary--output FILE — Write JSON to file
What It Shows:
- Photos from each previous year on the same date
- People, scenes, and best photo for each year
- Favorites count per year
- How many years ago each set of photos was taken
Example Output:
📅 ON THIS DAY
==================================================
Date: March 3
Photos found: 45 across 4 years
📆 2025 (1 year ago)
12 photos, ⭐ 3
👥 Jonah, Silas
🏷️ swimming, pool
📸 Best: IMG_1234.jpg Q:0.89
📆 2024 (2 years ago)
8 photos
👥 Jonah
🏷️ park, outdoor
Usage in Conversation:
User: "What did I do on this day in past years?"
AI: Runs on_this_day.py, narrates memories year by year
User: "Show me memories from March 3"
AI: Runs on_this_day.py --date 2026-03-03, tells the story
AI Tip: Narrate memories warmly! "2 years ago today, you were at the pool with Jonah and Silas — you took 12 photos and favorited 3 of them. The best shot has a quality score of 0.89!"
13. Album Auditor
Find orphan photos (not in any album), empty albums, tiny albums, and overlapping albums.
python3 scripts/album_auditor.py [--human]
Options:
--human — Human-readable summary--output FILE — Write JSON to file
What It Shows:
- Orphan photos count (not in any album)
- Empty albums that can be deleted
- Tiny albums (≤3 photos) that might be incomplete
- Album overlap (shared photos between albums, with percentages)
- Album size ranking
Example Output:
📁 ALBUM AUDITOR
==================================================
Total albums: 45
Albums with photos: 38
Empty albums: 4
Tiny albums (≤3 photos): 7
Photos in albums: 8,234 / 12,453
Orphan photos (no album): 4,219
📭 Orphan Photos:
4,219 photos not in any album
Total size: 18.3 GB
🗑️ Empty Albums (4):
• Old Vacation
• Test Album
🔄 Album Overlaps:
"Vacation 2024" ∩ "Summer 2024"
45 shared (12.3% / 8.9%)
Usage in Conversation:
User: "Are my photos well organized?"
AI: Runs album_auditor.py, reports orphans, empty albums, and overlap
User: "How many photos aren't in any album?"
AI: Runs album_auditor.py, reports orphan count and size
14. Cleanup Executor
Actually move junk photos to trash via AppleScript. Supports old screenshots, burst leftovers, low quality, and duplicates. All items go to Recently Deleted (recoverable for 30 days).
python3 scripts/cleanup_executor.py --category CATEGORY [--execute] [--human]
Options:
--category — What to clean up: old_screenshots, all_screenshots, burst_leftovers, low_quality, duplicates--screenshot-age N — Screenshot age in days for old_screenshots (default: 30)--quality-threshold N — Quality threshold for low_quality (default: 0.3)--limit N — Maximum items to process (default: 500)--execute — Actually perform the cleanup (without this, preview only)--batch-size N — Items per AppleScript batch (default: 50)--human — Human-readable summary
Safety:
- Without
--execute, shows preview only (dry run)
- With
--execute, requires typing 'yes' to confirm
- Items are moved to Recently Deleted (not permanently deleted)
- 30-day recovery window in Photos.app
- Uses AppleScript through Photos.app (never touches database directly)
Example Usage:
python3 scripts/cleanup_executor.py --category old_screenshots --human
python3 scripts/cleanup_executor.py --category old_screenshots --execute
python3 scripts/cleanup_executor.py --category burst_leftovers --execute
Usage in Conversation:
User: "Delete my old screenshots"
AI: Runs cleanup_executor.py --category old_screenshots --human first to show preview, then prompts user before running with --execute
User: "Clean up burst photos"
AI: Runs cleanup_executor.py --category burst_leftovers --human, shows count and size, asks for confirmation
⚠️ AI Tip: Always show the preview first! Never run with --execute without showing the user what will be affected and getting confirmation.
15. Live Photo Analyzer
Analyze Live Photos vs still photos: identify Live Photos, compare storage impact, find Live Photos that could be converted to stills to save space.
python3 scripts/live_photo_analyzer.py [--human] [--year YYYY] [--output FILE]
Options:
--year YYYY — Filter to specific year--human — Human-readable summary--output FILE — Write JSON to file
What it reports:
- Total Live Photos vs stills (count and storage)
- Playback style breakdown (live, loop, bounce, long exposure)
- Year-over-year Live Photo trends
- Estimated savings if Live Photos were converted to stills (~50% of video component)
- Unfavorited Live Photos as conversion candidates
- Largest Live Photos (biggest savings first)
16. Shared Library Analysis
Analyze the Shared Library in Apple Photos: personal vs shared content, contributor breakdown, storage impact.
python3 scripts/shared_library.py [--human] [--output FILE]
What it reports:
- Whether Shared Library is enabled
- Personal vs shared asset counts and storage
- Contributor identifiers and their contributions
- Shared content by year and monthly trends
- Photo/video split for shared content
Note: Requires macOS 13+ / iOS 16+ database format for Shared Library columns.
17. iCloud Sync Status
Check iCloud sync coverage across the library: synced vs local-only, download status, large unsynced items.
python3 scripts/icloud_status.py [--human] [--output FILE]
What it reports:
- Sync coverage percentage (synced vs local-only)
- Storage breakdown by sync state
- Photo vs video sync comparison
- Year-over-year sync trends
- Large local-only items (>10 MB) that aren't synced
- My assets vs others' assets
- Downloadable (cloud-only) item count
18. Photo Similarity Detection
Find visually similar photos beyond exact duplicates using computed quality feature vectors (composition, lighting, color, patterns, etc.).
python3 scripts/similarity_finder.py [--threshold 0.95] [--year YYYY] [--limit 500] [--human]
Options:
--threshold — Cosine similarity threshold 0-1 (default: 0.95, very similar)--year YYYY — Filter to specific year--limit N — Max photos to compare (default: 500, controls runtime)--human — Human-readable summary
What it reports:
- Groups of visually similar photos
- Potential storage savings per group
- Keep candidate (largest/highest quality in each group)
- Total extra (removable) similar photos
Runtime note: O(n²) comparison; use --limit to control runtime for large libraries.
19. Seasonal Highlights
Curate the best photos from each season using quality scores, favorites, and scene context.
python3 scripts/seasonal_highlights.py [--year YYYY] [--top 20] [--southern] [--human]
Options:
--year YYYY — Filter to specific year--top N — Top N photos per season (default: 20)--southern — Use Southern Hemisphere season definitions--human — Human-readable summary
What it reports:
- Best photos per season (spring, summer, fall, winter)
- Season-by-season quality scores and favorite counts
- Year-over-season distribution matrix
- Busiest season identification
- Best single photo per season
20. Face Quality Scoring
Score face quality per person using Apple Photos' face detection attributes: quality measure, blur, yaw angle, smile, face size, and center position.
python3 scripts/face_quality.py [--person NAME] [--top 10] [--human]
Options:
--person NAME — Filter to specific person name--top N — Top N best/worst per person (default: 10)--human — Human-readable summary
What it reports:
- Per-person face quality rankings
- Best and worst portraits per person
- Composite face score (quality, blur, size, yaw, smile, center)
- Overall library face quality average
- Most photographed person, highest quality person
Database Schema Reference
Detailed schema documentation is in references/database-schema.md. Key tables:
- ZASSET — Main photos/videos table
- ZADDITIONALASSETATTRIBUTES — File sizes, dimensions
- ZCOMPUTEDASSETATTRIBUTES — Apple's quality scores
- ZPERSON — Detected people
- ZDETECTEDFACE — Face detections
- ZGENERICALBUM — Albums
- ZSCENECLASSIFICATION — ML scene labels
Important: Core Data timestamps are seconds since 2001-01-01, not Unix epoch.
Common Workflows
Workflow 1: Quick Cleanup Assessment
python3 scripts/library_analysis.py --human
python3 scripts/junk_finder.py --human
Workflow 2: Free Up Storage
python3 scripts/storage_analyzer.py --human
python3 scripts/duplicate_finder.py --human
python3 scripts/junk_finder.py --screenshot-age 14 --quality-threshold 0.4 --human
Workflow 3: Year-End Photo Recap
python3 scripts/timeline_recap.py --start-date 2024-01-01 --end-date 2024-12-31 --narrative
python3 scripts/storage_analyzer.py | jq '.by_year'
python3 scripts/library_analysis.py | jq '.top_people'
python3 scripts/photo_habits.py --year 2024 --human
python3 scripts/best_photos.py --year 2024 --top 20 --human
Workflow 4: Export Organized Archive
python3 scripts/smart_export.py --output-dir ~/Desktop/Photos-Export --favorites --start-date 2024-01-01 --plan-only
Workflow 5: Deep Cleanup
python3 scripts/junk_finder.py --human
python3 scripts/cleanup_executor.py --category old_screenshots --human
python3 scripts/cleanup_executor.py --category old_screenshots --execute
python3 scripts/cleanup_executor.py --category burst_leftovers --execute
python3 scripts/album_auditor.py --human
Workflow 6: Daily Memory Check
python3 scripts/on_this_day.py --human
python3 scripts/on_this_day.py --window 2 --human
Workflow 7: Location & Travel Review
python3 scripts/location_mapper.py --human
python3 scripts/location_mapper.py --year 2025 --human
python3 scripts/scene_search.py --human
Workflow 8: People Deep Dive
python3 scripts/people_analyzer.py --human
python3 scripts/best_photos.py --hidden-gems --human
python3 scripts/face_quality.py --human
Workflow 9: Live Photo & Storage Optimization
python3 scripts/live_photo_analyzer.py --human
python3 scripts/similarity_finder.py --threshold 0.95 --human
python3 scripts/icloud_status.py --human
Workflow 10: Seasonal Year in Review
python3 scripts/seasonal_highlights.py --year 2024 --human
python3 scripts/location_mapper.py --year 2024 --human
python3 scripts/photo_habits.py --year 2024 --human
Workflow 11: Shared Library Audit
python3 scripts/shared_library.py --human
python3 scripts/shared_library.py --output shared_report.json
Tips for AI Assistants
When User Asks About Photos Cleanup
- Start with analysis — Run
library_analysis.py to understand the library
- Find junk — Run
junk_finder.py to quantify cleanup opportunities
- Be specific — Don't just say "you have junk photos," say "you have 287 screenshots older than 30 days (2.1 GB) that could be deleted"
- Explain savings — Always mention estimated storage savings
- Guide to Photos.app — Scripts identify candidates, but user must delete via Photos.app
When User Asks "What Did I Do?"
- Use timeline_recap — Perfect for narrative summaries
- Narrate, don't dump — Turn JSON into a story
- Highlight favorites — Mention standout moments
- Use emojis — Makes it more engaging
When User Asks About Storage
- Run storage_analyzer — Most comprehensive view
- Identify hogs — Call out the biggest files/categories
- Show trends — "You're adding about 1.5 GB per month"
- Suggest actions — "Deleting old screenshots could free up 2 GB"
When User Asks About Best/Favorite Photos
- Use best_photos — Shows quality distribution and top picks
- Highlight hidden gems — Use --hidden-gems to find unfavorited great shots
- Show scores — Explain what makes a photo high quality (composition, lighting, etc.)
When User Asks About People
- Use people_analyzer — Comprehensive people stats
- Show co-occurrences — "Jonah and Silas appear together in 2,100 photos"
- Show trends — "You photographed Jonah 40% less in 2025"
When User Asks "On This Day" / Memories
- Use on_this_day — Perfect for nostalgia
- Narrate warmly — Tell the story of each year
- Suggest window — If nothing found, suggest --window 2 for nearby dates
When User Wants to Actually Delete
- Always preview first — Run cleanup_executor without --execute
- Show counts and sizes — "287 old screenshots, 2.1 GB"
- Explain safety — Items go to Recently Deleted, recoverable for 30 days
- Get confirmation — Never auto-execute cleanup
Output Format Guidance
JSON output: Default for programmatic use, includes full details
Human output: Use --human flag for readable summaries
In conversation: Synthesize the data into natural language, don't just read the output
Requirements
- Python: 3.9+ (tested with 3.13)
- Platform: macOS only (Apple Photos database)
- Dependencies: None (uses only Python stdlib)
- Database: Read-only access to
~/Pictures/Photos Library.photoslibrary/database/Photos.sqlite
Safety & Permissions
- ✅ All operations are READ-ONLY — No photos are modified or deleted
- ✅ No external dependencies — Pure Python stdlib
- ✅ No Photos.app API — Direct SQLite reads (safe)
- ⚠️ Smart export uses AppleScript — Requires Photos.app to be running
- ⚠️ Cleanup executor uses AppleScript — Moves items to Recently Deleted (recoverable)
Limitations
- Read-only analysis — Scripts identify candidates, but cleanup must be confirmed by user
- Export via AppleScript — Requires Photos.app to be running
- Reverse geocoding — Offline lookup covers ~100 major world cities; remote locations show coordinates
- Similarity detection — Uses computed quality vectors (not pixel-level); O(n²) comparison limited by
--limit
- Shared Library columns — Requires macOS 13+ / iOS 16+ database format
- Empty library support — Scripts work on any library, but Matt's Mac mini library is empty (synced elsewhere)
- Schema changes — Apple may change database schema in future macOS versions
Troubleshooting
"Database not found"
→ Specify path with --library ~/Path/To/Photos Library.photoslibrary
"Permission denied"
→ Close Photos.app first, or run script while Photos.app is open (read-only is safe)
"No quality scores"
→ Not all photos have computed quality attributes; scripts handle NULLs gracefully
"Results don't match Photos.app counts"
→ Scripts exclude trashed items; Photos.app may show different views
Future Enhancements
All previously planned features have been implemented! Possible further expansions:
- Machine learning model export for custom photo classifiers
- Photo deduplication across multiple Photos libraries
- Integration with external photo services (Google Photos, Flickr)
- Time-lapse generation from photo sequences
- Custom smart album rule builder
- Photo metadata repair / bulk editing suggestions
Bottom line: This skill gives you X-ray vision into your Photos library. Use it to understand what you have, find what you don't need, and make cleanup decisions with confidence.
