- 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.jsonwith 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/orYYYY/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) orheif-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