photos

name	Photos
description	Organize, index, and search local photo libraries with AI-powered metadata and safe file handling.
metadata	{"clawdbot":{"emoji":"🖼️","requires":{"bins":["exiftool"]},"os":["linux","darwin","win32"]}}

Safety First

• Never delete photos directly — move to .photo-trash/ folder with original path preserved in filename
• Never overwrite originals — edits go to edited/ subfolder, originals stay untouched
• Before bulk operations, create manifest: photos-pending.json with planned actions for user review
• When user says "delete duplicates", move to trash and report count — let them empty trash manually

Indexing Strategy

• Create .photo-index/ in library root with one JSON sidecar per photo
• Sidecar filename: {original-hash}.json — survives renames and moves
• Index fields: hash, path, date_taken, camera, gps, description, tags, indexed_at
• Run indexing incrementally — skip files with matching hash already indexed
• Store description from vision analysis in sidecar, not in EXIF (non-destructive)

Vision Analysis (Token-Efficient)

• Don't analyze every photo upfront — index on-demand when user searches or asks
• Cache vision results permanently in sidecar JSON — never re-analyze same photo
• For bulk analysis, process in batches of 20 with progress updates
• Use concise prompts: "Describe this photo in 2-3 sentences. List people, objects, location, activity."
• Skip screenshots and memes (detect by aspect ratio + lack of EXIF) unless explicitly requested

Duplicate Detection

• Generate perceptual hash (pHash) alongside content hash — catches near-duplicates and resized copies
• Group duplicates by pHash similarity, keep highest resolution as "original"
• Report duplicates with thumbnails/paths, never auto-delete
• Consider EXIF date — oldest is likely the original, newer copies are backups

Search Patterns

• By content: Search sidecar descriptions with simple text match first, vision re-analysis if no hits
• By date: Parse EXIF DateTimeOriginal, fall back to file mtime
• By location: Reverse geocode GPS once, store city/country in sidecar for text search
• By person: If user identifies someone once ("that's Maria"), tag all similar faces in index

EXIF Handling

• Read: exiftool -json photo.jpg — returns all metadata as JSON
• Write date: exiftool -DateTimeOriginal="2024:03:15 14:30:00" photo.jpg
• Strip GPS before sharing: exiftool -gps:all= photo.jpg (operates on copy, not original)
• Batch read: exiftool -json -r /photos/ — recursive, outputs array

File Organization

• Propose structure, don't impose: YYYY/MM/ or YYYY/MM-DD/ based on user preference
• Rename pattern: YYYYMMDD_HHMMSS_originalname.ext — preserves original name, adds sortable prefix
• Handle timezone: EXIF dates are local time — ask user's timezone once, store in .photo-index/config.json
• HEIC to JPEG: sips -s format jpeg input.heic --out output.jpg (macOS) or heif-convert (Linux)

NAS/Remote Libraries

• For Synology/NAS: work with mounted paths, don't assume local speeds
• Test connection before bulk operations: ls /Volumes/photos | head -1
• For slow connections, build local index cache that syncs periodically
• Respect @eaDir (Synology thumbnails) and .DS_Store — skip in indexing