Search your entire Apple Photos library using Apple's own on-device index.

Natural visual phrases work best: 'sunset beach', 'receipt', 'dinner in Stockholm', 'whiteboard'. Filters narrow before ranking.

Args: query: What to find. Leave empty to browse by filter alone. limit: Maximum results (1-100). kind: 'photo' or 'video'. person: Only photos with this named face. album: Only photos in albums whose name contains this. place: Only photos taken somewhere matching this. year: Only photos from this calendar year. date_from: ISO date, inclusive lower bound (YYYY-MM-DD). date_to: ISO date, inclusive upper bound (YYYY-MM-DD). favorites_only: Only items hearted in Photos. screenshots: 'include', 'exclude', or 'only'. include_hidden: Include items in the Hidden album.

Actually look at photos: renders each one and returns it as an image.

Use this on the top few results of every search before answering a "find my photo of X" question. Works even for photos that live only in iCloud, because it reads Apple's own local thumbnails rather than the original.

Args: refs: Photo uuids from search results, or exact filenames. size: Longest edge in pixels (128-2048).

Everything known about specific photos: metadata, ML labels, place, albums, faces, and any text Apple read inside the image.

Args: refs: Photo uuids or exact filenames.

Size and shape of the library: totals, albums, named people, how much is indexed, and how much lives only in iCloud.

The visual words this library actually knows.

Apple's classifier has a closed vocabulary. When a search finds nothing, this is how to discover the word it does understand instead.

Args: starts_with: Only terms beginning with this prefix. limit: Maximum terms to return.

Export full-quality originals to a folder on this Mac.

Slow for iCloud-only assets: each one is downloaded first. Nothing is uploaded anywhere.

Args: refs: Photo uuids or exact filenames. directory: Absolute destination folder. Defaults to ~/Downloads/Photos Exports.

Diagnose setup: macOS, Full Disk Access, the library, the index, and whether writes are enabled. Run this first when anything misbehaves.

Heart photos in Photos, or remove the heart.

Args: refs: Photo uuids or exact filenames. favorite: False to un-favorite.

Set one photo's title.

Set one photo's description/caption.

Add keywords to photos, keeping the ones already there.

Add photos to an album, creating it if needed.

Args: album: Album name. refs: Photo uuids or exact filenames.

The closest thing to deleting that macOS allows.

Moves photos into an archive album so they leave the main library view. No app, including this one, can permanently delete photos by script, so the user empties that album by hand.

Args: refs: Photo uuids or exact filenames. confirm: The user reads this as deleting their photos. Set true only when they have actually asked for these specific items to go.