Apple Photos Cleaner

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:

1. Run library_analysis.py to get overview
2. Run junk_finder.py to identify cleanup candidates
3. Run duplicate_finder.py to find duplicates
4. 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:

1. Apple's built-in — Uses ZDUPLICATEASSETVISIBILITYSTATE
2. 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:

1. Search mode (--search beach) — Find all photos matching a scene label
2. 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:

# Preview what would be cleaned
python3 scripts/cleanup_executor.py --category old_screenshots --human

# Actually clean up (with confirmation prompt)
python3 scripts/cleanup_executor.py --category old_screenshots --execute

# Clean burst leftovers
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

# Get overview
python3 scripts/library_analysis.py --human

# Find junk
python3 scripts/junk_finder.py --human

# Review and manually clean up in Photos.app

Workflow 2: Free Up Storage

# Analyze storage
python3 scripts/storage_analyzer.py --human

# Find duplicates
python3 scripts/duplicate_finder.py --human

# Find junk with aggressive settings
python3 scripts/junk_finder.py --screenshot-age 14 --quality-threshold 0.4 --human

# Use findings to guide cleanup

Workflow 3: Year-End Photo Recap

# Generate timeline for the year
python3 scripts/timeline_recap.py --start-date 2024-01-01 --end-date 2024-12-31 --narrative

# Get storage stats by year
python3 scripts/storage_analyzer.py | jq '.by_year'

# Get top people for the year
python3 scripts/library_analysis.py | jq '.top_people'

# Photo habits for the year
python3 scripts/photo_habits.py --year 2024 --human

# Best photos of the year
python3 scripts/best_photos.py --year 2024 --top 20 --human

Workflow 4: Export Organized Archive

# Plan export
python3 scripts/smart_export.py --output-dir ~/Desktop/Photos-Export --favorites --start-date 2024-01-01 --plan-only

# Review plan, then execute (manual for now)

Workflow 5: Deep Cleanup

# Find all junk
python3 scripts/junk_finder.py --human

# Preview old screenshots
python3 scripts/cleanup_executor.py --category old_screenshots --human

# Execute cleanup (with confirmation)
python3 scripts/cleanup_executor.py --category old_screenshots --execute

# Clean burst leftovers
python3 scripts/cleanup_executor.py --category burst_leftovers --execute

# Check album health
python3 scripts/album_auditor.py --human

Workflow 6: Daily Memory Check

# See what happened on this day in past years
python3 scripts/on_this_day.py --human

# With a wider window
python3 scripts/on_this_day.py --window 2 --human

Workflow 7: Location & Travel Review

# See all your locations
python3 scripts/location_mapper.py --human

# Focus on trips from a specific year
python3 scripts/location_mapper.py --year 2025 --human

# What content you shot at those places
python3 scripts/scene_search.py --human

Workflow 8: People Deep Dive

# Who's in your photos
python3 scripts/people_analyzer.py --human

# Find hidden gems of specific people
python3 scripts/best_photos.py --hidden-gems --human

# Best and worst portraits per person
python3 scripts/face_quality.py --human

Workflow 9: Live Photo & Storage Optimization

# Analyze Live Photos vs stills
python3 scripts/live_photo_analyzer.py --human

# Find similar photos (potential duplicates)
python3 scripts/similarity_finder.py --threshold 0.95 --human

# Check iCloud sync status
python3 scripts/icloud_status.py --human

Workflow 10: Seasonal Year in Review

# Get seasonal highlights
python3 scripts/seasonal_highlights.py --year 2024 --human

# Location review with place names
python3 scripts/location_mapper.py --year 2024 --human

# Photo habits for the year
python3 scripts/photo_habits.py --year 2024 --human

Workflow 11: Shared Library Audit

# Check shared library status
python3 scripts/shared_library.py --human

# See who contributed what and storage impact
python3 scripts/shared_library.py --output shared_report.json

Tips for AI Assistants

When User Asks About Photos Cleanup

1. Start with analysis — Run library_analysis.py to understand the library
2. Find junk — Run junk_finder.py to quantify cleanup opportunities
3. 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"
4. Explain savings — Always mention estimated storage savings
5. Guide to Photos.app — Scripts identify candidates, but user must delete via Photos.app

When User Asks "What Did I Do?"

1. Use timeline_recap — Perfect for narrative summaries
2. Narrate, don't dump — Turn JSON into a story
3. Highlight favorites — Mention standout moments
4. Use emojis — Makes it more engaging

When User Asks About Storage

1. Run storage_analyzer — Most comprehensive view
2. Identify hogs — Call out the biggest files/categories
3. Show trends — "You're adding about 1.5 GB per month"
4. Suggest actions — "Deleting old screenshots could free up 2 GB"

When User Asks About Best/Favorite Photos

1. Use best_photos — Shows quality distribution and top picks
2. Highlight hidden gems — Use --hidden-gems to find unfavorited great shots
3. Show scores — Explain what makes a photo high quality (composition, lighting, etc.)

When User Asks About People

1. Use people_analyzer — Comprehensive people stats
2. Show co-occurrences — "Jonah and Silas appear together in 2,100 photos"
3. Show trends — "You photographed Jonah 40% less in 2025"

When User Asks "On This Day" / Memories

1. Use on_this_day — Perfect for nostalgia
2. Narrate warmly — Tell the story of each year
3. Suggest window — If nothing found, suggest --window 2 for nearby dates

When User Wants to Actually Delete

1. Always preview first — Run cleanup_executor without --execute
2. Show counts and sizes — "287 old screenshots, 2.1 GB"
3. Explain safety — Items go to Recently Deleted, recoverable for 30 days
4. 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.