[BUG]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude needs proper training on macOS Photos.app — current knowledge is dangerously wrong

本文:

## Problem

Claude's knowledge of macOS Photos.app scripting is fundamentally broken. It doesn't just make small mistakes —
it confidently uses APIs that don't exist and libraries that silently destroy user data.

## What happened in one session

1. Claude tried AppleScript remove to remove photos from an album. **This command does not exist in

Photos.app's AppleScript dictionary.** Claude kept trying variations instead of recognizing the API doesn't
support it.

1. Claude then switched to Python's photoscript library and called Album.remove(). This method internally

deletes the entire album and recreates it from scratch, changing the album UUID. Result: 6 garbage
duplicate albums created, user's manual organization destroyed.

1. When multiple albums had the same name (caused by #2), Claude targeted the wrong one because it matched by

name instead of ID.

1. Claude didn't know Photos.app uses content-hash deduplication, so it wasted time trying to import JPG

versions of photos that already existed as HEIC.

The user had to discover every correct approach themselves and teach Claude step by step. Hours of cleanup.

## What Claude needs to learn

The correct tool for each Photos.app operation:

| Operation | Correct | Wrong (Claude tried these) |
|-----------|---------|---------------------------|
| Remove photo from album | PhotoKit Swift: PHAssetCollectionChangeRequest.removeAssets() | AppleScript
remove (doesn't exist), photoscript.remove() (recreates album) |
| Add photo to album | AppleScript add | — |
| Import file | AppleScript import | — |
| List albums with IDs | PhotoKit PHAssetCollection | — |

Key behaviors Claude doesn't know:

• AppleScript's Photos dictionary has NO remove command for album membership
• photoscript Python library's remove() does delete→recreate internally — never safe to use
• Photos.app deduplicates by content hash, not filename — HEIC and JPG of same image = same photo
• Some albums exist in AppleScript but are invisible to PhotoKit
• Same-name albums require localIdentifier (ID), not name matching

## Ask

Please retrain Claude on macOS Photos.app APIs before it causes more data loss. This isn't an edge case — photo
management is a common macOS task. Claude should know the correct approach from the start, not learn it by
breaking things.

What Should Happen?

Please retrain Claude on macOS Photos.app APIs before it causes more data loss. This isn't an edge case — photo
management is a common macOS task. Claude should know the correct approach from the start, not learn it by
breaking things.

Error Messages/Logs

Steps to Reproduce

mac app

Claude Model

None

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

latest

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_