From immich-photo-manager
Generates a report on people in an Immich photo library: unique faces, photos per person, unnamed faces, co-occurrence patterns, and face recognition quality.
How this skill is triggered — by the user, by Claude, or both
Slash command
/immich-photo-manager:people-reportThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Before doing ANYTHING else in this skill, call `ping` on the Immich MCP server.**
Before doing ANYTHING else in this skill, call ping on the Immich MCP server.
ping succeeds → proceed with the skill normally.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:
- Your Immich server URL (e.g.,
http://192.168.1.100:2283)- An Immich API key (how to create one)
- The MCP server configured (see /setup-immich-photo-manager)
Nothing in this plugin will work until the connection is configured.
Do NOT skip this check. Do NOT try to run any other tool first. Always ping, always block if it fails.
Analyze Immich's face recognition data to generate a report on people in the library — who appears most, unnamed face clusters, co-occurrence patterns, and recognition quality.
Use the list_people MCP tool to get all people with pagination:
# Get all people (including hidden clusters)
result = list_people(page=1, size=200, with_hidden=true)
# Repeat with page=2, 3, … until result.hasNextPage is false
# Named: people where name is not empty
named = [p for p in result.people if p.name]
# Unnamed: people where name is empty
unnamed = [p for p in result.people if not p.name]
# Top named people by face count (result includes a faceCount field)
top_named = sorted(named, key=lambda p: p.faceCount, reverse=True)[:20]
# Unnamed clusters worth naming (more than 5 faces)
big_unnamed = [p for p in unnamed if p.faceCount > 5]
big_unnamed.sort(key=lambda p: p.faceCount, reverse=True)
Find people who appear together most often using get_asset_faces:
# For a sample of assets (e.g. from search_metadata), call get_asset_faces
# to find which people appear in the same photo
co_occurrence = {} # (person_a_id, person_b_id) → count
for asset_id in sample_asset_ids:
faces = get_asset_faces(asset_id=asset_id)
person_ids = [f.personId for f in faces if f.personId]
for i, a in enumerate(person_ids):
for b in person_ids[i+1:]:
key = tuple(sorted([a, b]))
co_occurrence[key] = co_occurrence.get(key, 0) + 1
# Sort and present top 15 pairs
top_pairs = sorted(co_occurrence.items(), key=lambda x: x[1], reverse=True)[:15]
Iterate named people from list_people and use get_person for details:
# For each named person, get_person returns birthDate and other metadata
# Use search_metadata with personIds to find their date range
timelines = []
for person in named:
details = get_person(person_id=person.id)
# Use search_metadata(person_ids=[person.id], order="asc", size=1) for first appearance
# Use search_metadata(person_ids=[person.id], order="desc", size=1) for last appearance
first = search_metadata(person_ids=[person.id], order="asc", size=1)
last = search_metadata(person_ids=[person.id], order="desc", size=1)
timelines.append({
"name": person.name,
"first": first.assets[0].localDateTime if first.assets else None,
"last": last.assets[0].localDateTime if last.assets else None,
"face_count": person.faceCount,
})
Use list_people with with_hidden=True to surface hidden clusters, and get_person_thumbnail to visually inspect unnamed ones:
# Hidden clusters — often low-confidence or suppressed by Immich
all_people = list_people(page=1, size=500, with_hidden=True)
hidden = [p for p in all_people.people if p.isHidden]
# For each unnamed cluster worth reviewing, fetch a thumbnail to show the user
for cluster in big_unnamed[:10]:
thumb = get_person_thumbnail(person_id=cluster.id)
# Present thumbnail so user can decide whether to name or merge
display(thumb)
# Report recognition quality tiers based on faceCount
large_clusters = [p for p in unnamed if p.faceCount > 50] # almost certainly real people
medium_clusters = [p for p in unnamed if 10 < p.faceCount <= 50]
small_clusters = [p for p in unnamed if p.faceCount <= 10] # may be noise
PEOPLE REPORT
═══════════════════════════════════════
OVERVIEW
Total face clusters: 287
Named people: 42
Unnamed clusters: 245 (85%)
Total faces detected: 18,432
TOP PEOPLE (by photo count)
1. María 2,341 photos (2014-2026)
2. Juan 1,892 photos (2014-2026)
3. Carlos 634 photos (2018-2025)
4. Ana 412 photos (2016-2024)
5. Pedro 287 photos (2019-2023)
...
UNNAMED CLUSTERS WORTH NAMING
Cluster #45: 189 faces (appears 2019-2024) — likely a real person
Cluster #112: 87 faces (appears 2020-2023)
Cluster #78: 64 faces (appears 2021-2025)
...12 more clusters with >20 faces
→ Naming these 15 clusters would increase named coverage from 58% to 82%
CO-OCCURRENCE (people appearing together)
María & Juan: 1,204 photos together
María & Carlos: 287 photos together
Juan & Pedro: 156 photos together
...
RECOGNITION GAPS
Photos with faces but no person assigned: 2,341
Very small faces (<100px): 4,521 (may have lower accuracy)
RECOMMENDATIONS
1. Name the top 15 unnamed clusters → big coverage improvement
2. Review 2,341 unassigned faces in Immich UI
3. Consider merging similar unnamed clusters
4. 4,521 small faces may produce false matches — review if face groups seem wrong
get_person_thumbnail to show faces and ask user to name themupdate_person(person_id, name="...") to name an unnamed cluster directly via MCPmerge_people(source_person_id, target_person_id) to combine similar unnamed clustersreassign_face(face_id, person_id) to correct wrong assignmentsnpx claudepluginhub drolosoft/immich-photo-manager --plugin immich-photo-managerMonitors an Immich photo library for new photos that match existing albums using GPS location, CLIP visual similarity, and date patterns, then suggests album additions.
Registers people or objects with reference images and searches for them across indexed videos using entity search. Useful for finding specific individuals or tracking objects in video content.
Bulk-retouch a folder of portrait photos using Adobe tools with auto-straighten, auto-tone, and auto-light. Designed for wedding and event photographers needing walk-away batch processing.