Build a Photo Sorter App with Claude Code

Turn a folder of photos and videos into an organised library with a single-page app you build in Claude Code. The brief below asks for one index.html file, a thumbnail-sorting animation, and an explicit confirmation before any files are copied or moved.

The sorter uses colour, brightness, image dimensions, filenames and video duration rather than an AI classification model. Its categories are useful heuristics, not a guarantee that it understands the subject of every photo.

What you will build

• A local browser app with no build step or paid classification API.

• A visual pile of thumbnails that flies into category cards, suitable for a screen recording.

• Separate Sort and Organise actions: the animation previews the result; only Organise changes files.

• Copy and Move modes, duplicate review, and a session-based Undo log.

Who this is for

• Founders and creators with a messy camera roll.

• Anyone filming a sort-my-photos reel.

• Beginners who want to build a useful tool from a detailed prompt.

What you need

• Claude Code, in the desktop app or terminal, with access to a project folder.

• A current desktop version of Google Chrome or Microsoft Edge.

• A disposable folder of copied photos and videos for testing.

• A screen recorder, if you want to film the animation.

This is a build brief, not a downloadable or pre-tested app. Claude Code access and usage limits are separate from the generated app, which needs no paid sorting API. Keep a separate backup and review the tests for your generated version before using it on a larger folder.

Part 1: Build it

1. Open Claude Code in an empty folder

1. Create a folder called photo-sorter.

2. Open it as your project in Claude Code on desktop or in the terminal.

3. Start a new session.

An empty project folder keeps the generated app separate from the photos you will sort. For setup details, see the Claude Code desktop documentation.

2. Paste the build prompt

Copy the entire prompt below into Claude Code. It specifies the design, animation, category rules and file operations. Keep the safety and test sections intact.

Build prompt: Photo Sorter

Build me a "Photo Sorter": one self-contained index.html file (no build step, no server, no paid APIs) that I open in Google Chrome. It sorts a folder of photos and videos into subfolders on my computer, with a satisfying animation I can screen-record for social media.

## Look and feel
- Calm, minimal "app window": light warm-grey background, one big rounded off-white card filling the screen, thin borders, soft shadow.
- Fonts: Inter for UI and Instrument Serif italic for one highlighted word, with system-font fallbacks. Google Fonts may be loaded for styling, but the app must still work without them. Never upload file contents or thumbnails.
- Header: small breadcrumb "Personal / Sorter", then a big title "Sorting my [folder name] folder". The folder name is in italic serif and filled in automatically from the folder I pick. Clicking the title lets me edit it.
- Stats row under the title: Total files · Photos · Videos · Duplicates · Space to free. Big bold numbers with tiny uppercase grey labels.
- Three columns below:
  - Left: "Photos" with 6 category cards in a 2×3 grid.
  - Middle: the "pile" area, with a small status line underneath ("Scanning… 312 / 1,065", "Press Sort", "All sorted ✓ in 6.4s").
  - Right: "Videos" with 3 cards, then "Cleanup" with 2 cards.
- Each category card: coloured dot, name, a count pill on the right, and an empty area where thumbnails land in a neat grid.
- A small dark floating toolbar in the bottom-right: Choose folder, Demo, Replay, Sort, Organise.

## The animation (this is the money shot)
1. Scanning: each file gets a square thumbnail that pops into the middle with a little bounce. Together they form a big circular pile, laid out in a sunflower spiral (phyllotaxis) from the centre outward. Tiles overlap slightly, are randomly tilted, and have a white border and soft shadow like tiny polaroids. The whole pile rotates very slowly. "Total files" counts up as tiles appear.
2. Sorting (Space key or the Sort button): tiles leave the pile in random order, slowly at first and then faster and faster. Each one flies along a curved arc into its category card, straightens out and shrinks to fit that card's grid. Each card's count pill bumps as a tile lands, and the stats count up live. The whole sort takes 5–8 seconds no matter how many files there are.
3. Done: the status says "All sorted ✓ in X.Xs" and the Organise panel appears.
- Performance: one requestAnimationFrame loop and only CSS transforms (translate, rotate, scale). Never animate width, height, top or left. Animate at most 1,500 tiles, but still sort and organise every file.
- Each card works out its own tile size so all its files fit inside it.

## How files are categorised (all in the browser, no AI API)
For each image, draw a 96px centre-cropped thumbnail on a canvas and read its average colour, its brightness and whether it's taller or wider. For videos, read the duration from the metadata and grab a frame at 1 second for the thumbnail. Run 6 files at a time.
- Photos/Screenshots: the filename contains "screenshot", or it's a PNG with a phone-screen shape.
- Photos/Night & moody: brightness below 0.3.
- Photos/Golden hour: clearly more red than blue, and not dark.
- Photos/Sky & sea: more blue than red.
- Photos/Portrait shots: taller than wide.
- Photos/Everyday shots: everything else, including images the browser can't decode (like HEIC in Chrome).
- Videos/Quick clips (under 10s), Videos/B-roll (10–60s), Videos/Long takes (over 60s).
- Duplicates: group files by byte size, then compare their complete contents before classifying them as duplicates. A SHA-256 hash of only the first and last 4 MB may shortlist large-file candidates, but it is not proof of equality. Confirm every candidate with a full chunk-by-chunk byte comparison; use bounded memory for large files. Keep the copy with the shortest name as the original. If verification fails, leave it in its normal category and report it as unverified.
- Docs & other: everything else, shown as a pale tile with the file extension (PDF, ZIP…).

## Actually organising the files (safety first)
- Feature-detect the File System Access API. Call showDirectoryPicker({ mode: "readwrite" }) only from a user click. Also support folder drag-and-drop where available, and request write permission before organising. Keep the picker button as a fallback.
- Only touch files directly inside the chosen folder. Never go into its subfolders.
- After the animation, show a panel in the middle: "Organise N files? They'll go into X folders inside [folder]. Duplicates go into their own folder for review; no automatic duplicate cleanup." Give me a toggle between "Move files" and "Copy, keep originals", defaulting to Copy, plus the buttons "Organise my files" and "Not now". Explain that Move removes the source entry only after the destination is verified.
- Show a progress bar while it works, handling 4 files at a time.
- Moving: do not assume FileSystemHandle.move() works outside the Origin Private File System. Use a supported native move only after testing it on a disposable user-selected folder. Otherwise copy, close the destination writer, and verify size AND complete contents against the unchanged source before removing the source entry. If verification, permissions or source stability checks fail, keep the original and report the failure.
- Never overwrite: if a name already exists in a folder, save it as "name (1).jpg".
- Never automatically delete duplicates or discard the only verified copy. Copy mode never removes originals. Move mode may remove a source entry only after a verified destination exists. Duplicates are organised into a Duplicates folder for manual review. "Space to free" is an estimate, not space already reclaimed.
- Keep a per-file undo log and show "✓ N files organised" plus Undo. In Move mode, Undo restores files without overwriting any newly created originals. In Copy mode, Undo leaves originals alone and removes only unchanged copies made by this operation. Verify file identity and contents before any removal; on conflicts, keep both and report them. Remove only empty folders created by this run. Explain that Undo is limited to the current session and is not a backup.
- If some files fail, keep going and list those files at the end.
- In Safari or Firefox, still show the animation, but explain that organising for real needs Chrome or Edge.

## Extras
- A Demo button that makes about 600 fake colourful "photos" (sunsets, night skies, ocean, screenshots, a few videos, docs and duplicates), so I can try the animation without choosing a folder. In demo mode, Organise only explains that it's a demo.
- Keyboard: Space = sort, R = replay the animation for another take (without scanning again), H = hide or show the toolbar, F = fullscreen.
- The toolbar fades out while sorting, so recordings look clean.

## Before you give it to me
- Run the Demo in a browser and check the animation works with no console errors.
- Test move, copy and mode-specific undo using generated fixtures: images, a duplicate, a PDF, a video, filename collisions, and same-size files with identical first/last chunks but different middle bytes. Check interrupted copies and changed destinations do not lose originals. OPFS tests do not prove that a user-selected folder works: also test the actual directory picker and permissions with a disposable local folder. Never test on my real photos. If your environment cannot run a check, say so and give me the exact manual test instead of claiming success.
- Then tell me in plain steps how to open it in Chrome, and what to do if Chrome won't let it edit a folder opened straight from a file (offer a one-line local server command as a backup).

3. Review the build and test results

Let Claude generate index.html, then review what it actually tested.

1. Answer any questions about your setup.

2. Check that the Demo runs without browser console errors.

3. Check the reported results for Copy, Move and Undo on disposable files, including filename collisions.

4. Confirm that index.html exists in the project folder.

5. Ask Claude to fix failures before continuing. If it could not test your browser's real folder access, complete that manual test yourself.

Tests in the browser's Origin Private File System do not replace a test on a user-selected folder. Browser support for moving files can differ between those two locations; see Chrome's file-system guidance.

Part 2: Before you sort

4. Prepare a small test folder

Do not select your Mac Photos Library. Export copies from Photos rather than touching files inside Photos Library.photoslibrary.

To export:

1. Select photos in the Photos app.

2. Choose File → Export → Export Photos…

3. Choose JPEG as the photo kind.

4. Save around 20 copies in a new test folder, separate from the app project.

JPEG avoids relying on HEIC decoding in the browser. If an image cannot be decoded, the requested fallback is Everyday shots; that does not mean its colours were analysed successfully.

Only files directly inside the selected folder are scanned. Existing subfolders are ignored. Keep a separate backup, try Copy first, and test Move and Undo only on disposable copies before scaling up.

Part 3: Run it

5. Open the app in Chrome or Edge

Open index.html in your desktop browser. If opening the file directly prevents folder access, ask Claude for a local server command appropriate to your computer, run it from the project folder, and open the local address it provides.

Real folder organisation depends on the browser exposing the required directory picker and granting write access. In an unsupported browser, the app should keep Demo available and explain the limitation instead of pretending to move files.

6. Choose your test folder

1. Click Choose folder in the toolbar, or drag in a folder if your browser supports it.

2. Select the small test folder.

3. Allow editing when the browser requests permission.

4. Watch the thumbnail pile form while Total files counts up.

5. Check the auto-filled title, such as “Sorting my Test folder”. Click it to change the display title for your recording.

7. Play the sorting animation

1. Wait for Press Sort.

2. Press Space or click Sort.

3. Watch the tiles move into category cards. The prompt targets a five-to-eight-second animation; actual performance depends on the generated implementation and your device.

4. Wait for All sorted ✓ and the Organise panel.

Filming tip: press H to hide the toolbar and F for fullscreen. Start recording before pressing Space. Press R to replay without scanning again. At most 1,500 tiles are animated, while all scanned files still need to be accounted for.

Part 4: Organise and review

8. Confirm the file operation

The animation is a preview. Files stay in place until you confirm Organise my files.

1. Check the file count, destination folders and selected source folder.

2. Start with Copy, keep originals. Choose Move files only after testing and backing up.

3. Click Organise my files, or Not now to cancel.

4. Watch the progress bar; the requested implementation handles four files at a time.

5. Review the completion count and any failed-file list.

The prompt requires collision-safe names such as name (1).jpg. In Move mode, removing a source entry is allowed only after its destination has been verified. A failed copy or verification must leave the original intact.

9. Use Undo if needed

• After Move: Undo should restore files to their original locations without overwriting files created since the operation.

• After Copy: Undo should leave the originals untouched and remove only unchanged copies created by that operation.

• On conflicts or changed files: keep both versions and inspect the reported issue.

• Created folders: remove only those that are empty and were created by the current run.

Keep the tab open until you have checked the result. The requested Undo log is session-based; it does not replace a backup or guarantee recovery after the tab closes.

10. Review duplicates yourself

Open the Duplicates folder in Finder or File Explorer and inspect the files before deleting anything yourself. The app should never perform automatic duplicate cleanup.

The shortest filename is retained as the original within a confirmed duplicate group. Equal file sizes, or matching hashes of only the beginning and end, do not establish that the complete files match. The revised prompt requires a full byte comparison before classifying a duplicate. If verification cannot finish, keep the file and mark it unverified.

The Space to free number is an estimate for review. Moving duplicate files to a different folder does not reclaim disk space; Copy mode can use more space.

Reference: sorting rules

Apply the photo rules in the order below, using the first match. Confirmed duplicates take precedence; files that cannot be decoded use the fallback category.

• Photos / Screenshots: the filename contains “screenshot”, or a PNG has a phone-screen shape.

• Photos / Night & moody: brightness below 0.3 on a 0–1 scale.

• Photos / Golden hour: clearly more red than blue, and not dark.

• Photos / Sky & sea: more blue than red.

• Photos / Portrait shots: taller than wide.

• Photos / Everyday shots: remaining photos, including unsupported image formats.

• Videos / Quick clips: under 10 seconds.

• Videos / B-roll: 10–60 seconds, inclusive.

• Videos / Long takes: over 60 seconds.

• Duplicates: complete contents match; keep the shortest-named file as the original.

• Docs & other: remaining files, displayed as pale tiles with their extensions.

These labels describe the requested rules, not semantic recognition. A blue object can land in Sky & sea, and a portrait-oriented landscape can land in Portrait shots.

Keyboard shortcuts

• Space: sort.

• R: replay the animation without scanning again.

• H: hide or show the toolbar.

• F: enter fullscreen.

Troubleshooting

The browser will not edit the folder

Click Choose folder again and allow editing. If the page was opened directly from a file and access remains blocked, use the local server instructions from Claude. Confirm that the browser supports the required directory picker.

Photos all land in Everyday shots

Check whether the browser can decode them. Export JPEG copies from Photos and try those instead of relying on HEIC support.

Organise does nothing

Check that you selected a real folder rather than Demo, and that you granted write access in a supported desktop browser.

Some files fail

Check for locked files, insufficient disk space or changed permissions. Keep the originals, inspect the failed-file list, and retry only after resolving the cause.

The animation or scan is slow

Try a smaller folder first. The 1,500-tile animation cap does not limit the number of files scanned. Decoding videos and comparing complete duplicate candidates can take longer than the animation itself.

Technical references

• Chrome: File System Access API — permission handling, directory access, drag-and-drop and move limitations.

• MDN: SubtleCrypto.digest — hashing requires the supplied input in memory; partial-input hashes are not full-file verification.