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