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