Clipboard Image Archive

What it does

Saves any PNG on the macOS clipboard to ~/apps/cc/screenshots/{timestamp}.png every time a prompt is submitted in Claude Code. Full resolution, no compression. Deduplicated by content hash so the same image does not get saved twice in a row. The save path is announced in the next system reminder block so both James and Claude can see it happened.

The point: images pasted into chat are no longer ephemeral. If James or Claude needs the original later — for higher-resolution extraction, archival, or reuse in other artifacts — the file is already on disk.

When to use

Passive. There is no invocation. The capability fires automatically on every UserPromptSubmit, scoped to whatever is on the clipboard at that exact moment.

Retrieval is active. To grab a recent image by eye, look at the screenshots directory sorted by modification time. To grab by time, match the timestamp in the filename to the moment the prompt was sent.

ls -t ~/apps/cc/screenshots/ | head -5

How to invoke

Nothing to invoke. The hook runs on every submitted prompt. To verify it is wired up:

grep save-clipboard-image ~/.claude/settings.json

Prerequisites

• macOS. The hook uses osascript to read the clipboard as «class PNGf».
• Clipboard must contain PNG data at submit time. TIFF does not currently trigger the save (unlike clipboard-image.sh which falls back to TIFF). Worth adding later.
• The hook path at ~/apps/cc/hooks/save-clipboard-image.sh must exist and be executable.

Where it lives

• Hook script: ~/apps/cc/hooks/save-clipboard-image.sh
• Settings registration: ~/.claude/settings.json under hooks.UserPromptSubmit
• Image archive: ~/apps/cc/screenshots/
• Dedup state: ~/apps/cc/screenshots/.last-hash (last saved PNG’s MD5)

What it catches

• macOS screenshots from Cmd-Shift-4 or Cmd-Shift-5 when configured to copy to clipboard
• Images copied from a browser, Finder, or any native app via Cmd-C
• Sticker reactions pasted from iMessage or other apps
• Anything in the clipboard at UserPromptSubmit time, even if the user did not explicitly reference the image in the prompt text

What it does NOT catch

• Drag-and-drop file attachments into the Claude Code chat pane — those bypass the clipboard
• File-picker attachments via the paperclip icon — also bypass the clipboard
• Inline markdown image URLs — these are URL references, not image data
• TIFF-formatted clipboard content (future improvement)

Example session

James submits a prompt with a screenshot on his clipboard. The hook fires, detects PNG data, writes the file, and prints the save path in the system reminder:

📸 Screenshot saved: /Users/ojhurst/apps/cc/screenshots/2026-04-18_22-27-56.png

Claude reads the path, then retrieves the image later via the standard Read tool when needed.

How to update this page

• If the hook gains TIFF fallback, note that under “What it catches.”
• If the archive directory changes, update both “Where it lives” and the example.
• If the filename convention changes (e.g., adding the prompt ID prefix), update the retrieval example.

Known gaps

• TIFF support. clipboard-image.sh already falls back to TIFF via sips; the auto-save hook does not. Easy port.
• No index. 875 images and growing, organized only by timestamp. A monthly index HTML with thumbnails would help retrieval.
• No tie to prompt text. The hook has no idea what James wrote when the image was captured. A sidecar text file per image (with the prompt that triggered it) would make the archive searchable.
• No pruning. The directory grows forever. A retention policy or quarterly archive-to-Drive step would keep it manageable.

Related

• Redact Images — blur or black-bar PII out of these archived screenshots before sharing.
• Generate an Image — the outbound sibling: produce fresh images via Gemini Nano Banana.
• Sibling script for explicit clipboard grabs: ~/apps/cc/recipes/clipboard-image.sh (same clipboard logic, writes to a user-specified path).