Photo Search

Connection Required — ALWAYS CHECK FIRST

Before doing ANYTHING else in this skill, call

ping

• If

  ping

  succeeds -> proceed with the skill normally.
• If

  ping

  fails or the MCP tools are not available -> STOP. Do not continue. Tell the user:

Immich is not connected. This plugin needs a running Immich MCP server to work.

Run /setup-immich-photo-manager to configure your Immich connection. You'll need:

1. Your Immich server URL (e.g.,

   http://192.168.1.100:2283

   )
2. An Immich API key (how to create one)
3. The MCP server configured (see /setup-immich-photo-manager)

Do NOT skip this check. Do NOT try to run any other tool first. Always ping, always block if it fails.

CRITICAL RULE: NEVER CREATE TEMPORARY ALBUMS

This is the most important rule of this skill. NEVER create albums as part of a search workflow.

The user has a curated library of real albums. Creating temporary albums pollutes their library with junk. Instead:

• If photos belong to a real album -> use that real album directly
• If photos are NOT in any album -> show them directly using

  get_thumbnails_batch

• NEVER call

  create_album

  from this skill. Not for "temp" albums, not for "search results", not for any reason.

Search Workflow (Step by Step)

Step 1: Parse user intent

Identify what the user is looking for. Determine which search dimensions apply.

Step 2: Search for matching photos

Use

search_metadata

search_smart

IMPORTANT — Immich EXIF location quirks:

• Immich stores cities as municipalities, not tourist names. "Tikal" does not exist as a city — it's in the municipality of "Flores" (state: "Petén", country: "Guatemala").
• "Lanzarote" does not exist as a city — look for municipalities like "Arrecife", "Yaiza", "Teguise", "Haría", etc. (state: "Canary Islands", country: "Spain").
• When a place-name search returns 0 results, try broader terms: search by state or country instead of city, then filter. Or use

  search_smart

  with the place name as a CLIP query.

Search strategy priority:

1. search_metadata(city=...)

   — fastest, most precise if the city name matches

2. search_metadata(state=...)

   or

   search_metadata(country=...)

   — broader, catches municipalities

3. search_smart(query="...")

   — AI/CLIP semantic search, catches things without GPS

Step 3: Find REAL matching albums

Call

list_albums()

Examples:

• User asks "photos of Tikal" -> match album "Tikal & Petén" (and possibly "Guatemala")
• User asks "fotos de la Barceloneta" -> match album "Barcelona — Barceloneta / Playa"
• User asks "Valle del Jerte" -> match album "Valle del Jerte & Hervás"
• User asks "Lanzarote" -> match albums containing "Lanzarote" in their name

Matching rules:

• Case-insensitive substring match on album name
• Also check album descriptions
• The query terms can appear anywhere in the album name (e.g., "Tikal" matches "Tikal & Petén")
• Include albums for broader regions if relevant (e.g., for "Tikal" also include "Guatemala")

Step 4: Collect asset metadata for the gallery

Two paths depending on whether a real album was found:

Path A — Real album found (preferred)

Use

get_album(album_id)

id

originalFileName

fileCreatedAt

Path B — No matching album (orphan photos)

Use the search results directly — they already contain

id

originalFileName

fileCreatedAt

Fetch thumbnails as base64 using

get_thumbnails_batch(asset_ids=[...], size="thumbnail", limit=50)

about:

data:

Step 5: Build and present the HTML gallery

1. Read the template:

   assets/viewer-template.html

   from the plugin root
2. Replace all

   {{PLACEHOLDERS}}

   with actual data
3. Write the HTML to the outputs directory
4. Present via

   computer://

   link

For Related Albums ({{ALBUMS_JSON}}):

• Include ONLY real albums found in Step 3
• If no real albums matched, use an empty array

  []

• NEVER fabricate album entries

Search Capabilities

search_smart(query=...)

search_metadata(city=..., state=..., country=...)

search_metadata(taken_after=..., taken_before=...)

search_metadata(make=..., model=...)

search_metadata(asset_type=...)

search_metadata(is_favorite=true)

Query Translation

search_metadata(country="Italy")

list_albums()

search_smart(query="sunset")

search_metadata(taken_after="2025-12-20", taken_before="2025-12-31")

search_metadata(is_favorite=true)

search_metadata(make="Apple")

search_metadata(city="Barcelona", asset_type="VIDEO")

search_metadata(state="Petén")

search_smart(query="Tikal")

Gallery HTML Generation

Template

Use the canonical template at

assets/viewer-template.html

{{PLACEHOLDERS}}

Placeholder Rules

• {{PAGE_SIZE}}

  ,

  {{PHOTO_COUNT}}

  ,

  {{ALBUM_TOTAL}}

  : Should be plain integers (e.g.

  20

  ). The template uses

  parseInt()

  with fallbacks, so non-numeric values degrade gracefully (PAGE_SIZE defaults to 6, others to 0).

• {{ALBUM_NAME}}

  : Can contain any characters including apostrophes (e.g. "L'Hospitalet"). Safe in HTML contexts. The JS alt-text reads from

  document.title

  instead of re-injecting this placeholder, so apostrophes won't break JS.

• {{SEARCH_QUERY}}

  ,

  {{IMMICH_URL}}

  : Can be any string.

• {{PHOTO_ENTRIES}}

  : Must be valid JS object literals, comma-separated.

• {{ALBUMS_JSON}}

  : JSON album objects. The template wraps them in

  [...].flat()

  , so you can pass any of these formats:
  • Comma-separated objects:

    {"id":"abc","name":"X","total":50},{"id":"def","name":"Y","total":30}

  • A JSON array:

    [{"id":"abc","name":"X","total":50}]

  • Empty string (no albums): the template produces

    [].flat()

    →

    []

    and hides the section

Thumbnail Delivery Strategies

There are three strategies for delivering thumbnails to the gallery viewer, with different trade-offs. The strategy used depends on the user's Immich setup and the viewing context.

Strategy 1: Base64 Embedded (Default — Always Works)

The Cowork viewer runs in an

about:

fetch

<img src>

data:

Each photo entry in

{{PHOTO_ENTRIES}}

{src:'data:image/jpeg;base64,/9j/4AAQ...',id:'<asset-id>',name:'<filename>',date:'<ISO-date>'}

• src

  : Base64 data URI of the thumbnail (from

  get_thumbnails_batch

  , size=thumbnail, ~250px, ~15-25KB each)

• id

  : The Immich asset ID (for linking to Immich web UI)

• name

  : Original filename (displayed as label)

• date

  : ISO date string from the asset metadata

Always use

size="thumbnail"

preview

How to get thumbnails: Call

get_thumbnails_batch(asset_ids=[...], size="thumbnail", limit=50)

Limitations: HTML file size grows linearly with photo count (~18KB per photo). Not ideal for albums with hundreds of photos. Maximum practical limit is ~50 thumbnails per gallery file.

CORS-Enabled Direct URLs (Optional — Requires User Setup)

If the user has configured CORS headers on their Immich reverse proxy, the gallery HTML can use JavaScript

fetch()

x-api-key

This requires the user to configure their reverse proxy (Nginx, Caddy, Traefik, etc.) to return CORS headers. See the Post-Install: CORS Configuration section in

/setup-immich-photo-manager

Advantages: Works for any photos (albums or search results), tiny HTML file, true on-demand pagination, no shared links needed.

Limitations: Requires CORS configuration on the server side. Not available out of the box.

Strategy Decision Flow

Always use Base64 Embedded (Strategy 1) as the default:
  ├─ ≤50 photos → Embed all thumbnails as base64
  └─ >50 photos → Embed first 50 in batches, warn user about file size and total count

Note: CORS-enabled direct URLs (Strategy 3) are an opt-in enhancement for users who open galleries in a regular browser. They do NOT work inside the Cowork sandbox. Never mention strategy numbers or internal labels in user-facing output — just generate the gallery silently using the correct approach.

Template lazy loading

The first page (PAGE_SIZE photos) loads immediately. Subsequent pages use IntersectionObserver to set

src

dataset.src

Albums JSON Format

{{ALBUMS_JSON}}

{"id":"abc123","name":"Tikal & Petén","total":169},{"id":"xyz789","name":"Guatemala","total":392}

Comma-separated JSON objects — NO outer array brackets (the template adds

[...]

Generation Workflow (Concrete Example)

User: "show me photos of Tikal"

1. ping() -> OK
2. search_metadata(state="Petén", country="Guatemala") -> found 200+ assets
3. list_albums() -> scan names -> found "Tikal & Petén" (id: d6dd63d0, 169 photos), "Guatemala" (id: 8dde4bb1, 392 photos)
4. get_album(album_id="d6dd63d0") -> get asset list with IDs, names, dates
5. get_thumbnails_batch(asset_ids=[...], size="thumbnail", limit=50) -> base64 JPEG data for first 50 photos
6. Read assets/viewer-template.html
7. Replace placeholders:
   - {{ALBUM_NAME}} -> "Tikal & Petén"
   - {{ALBUM_TOTAL}} -> 169
   - {{SEARCH_QUERY}} -> "Tikal"
   - {{IMMICH_URL}} -> "https://your-immich-server.com"
   - {{PAGE_SIZE}} -> 20
   - {{PHOTO_COUNT}} -> 50 (limited to 50 for file size)
   - {{PHOTO_ENTRIES}} -> {src:'data:image/jpeg;base64,...',id:"abc",name:"IMG_001",date:"2023-06-15"}, ...
   - {{ALBUMS_JSON}} -> {"id":"d6dd63d0","name":"Tikal & Petén","total":169},{"id":"8dde4bb1","name":"Guatemala","total":392}
8. Write tikal.html to outputs (~0.9MB with 50 base64 thumbnails, total album has 169 photos)
9. Present computer:// link

When photos are NOT in any album

User: "show me sunset photos"

1. ping() -> OK
2. search_smart(query="sunset") -> found 35 assets (each has id, originalFileName, fileCreatedAt)
3. list_albums() -> no album name matches "sunset"
4. Read template
5. Replace placeholders:
   - {{ALBUM_NAME}} -> "Sunset Photos"
   - {{ALBUM_TOTAL}} -> 35
   - {{PHOTO_COUNT}} -> 35
   - {{PHOTO_ENTRIES}} -> entries built from get_thumbnails_batch (base64 src + id + name + date)
   - {{ALBUMS_JSON}} ->     <-- empty string, no real albums match
6. Write sunset-photos.html to outputs (~0.7MB with base64 thumbnails)
7. Present computer:// link

Result Presentation

When showing search results:

• Count first: "Found 147 photos matching your search"
• Real albums: "These photos are in your album 'Tikal & Petén' (169 photos)"
• Date range: "Spanning from June 2019 to June 2023"
• Visual preview: Always generate the HTML gallery viewer
• Action prompt: Suggest next steps (see more photos, explore related albums, etc.)

Pagination

Immich API returns paginated results. For large result sets:

• Fetch first page to get total count
• Report total to user before fetching all pages
• For browsing, show first page thumbnails and offer to load more

Advanced Search Patterns

Finding screenshots

No GPS data + screen-resolution dimensions + no lens/focal length EXIF.

Finding duplicates

Same date range across import sources. Compare by exact hash, timestamp + dimensions, or CLIP similarity.