# Screenshot Flow for Claude Code — paste the path, not the pixels (Mini Tool)

Stop pasting screenshots into your AI coding terminal. A pasted image gets encoded as
base64 text and stored inside the conversation, then travels with every request you send
for the rest of the session — whether the AI ever needs to look at it again or not. This
sets up a lighter flow: every screenshot you take is saved to a folder with a clean
timestamped name, and Claude finds it by itself when you say "look at the screenshot I
just took." No pasting, no dragging, no wasted context. Works on macOS, Windows, and Linux.

## How to use it (any OS)
Two ways — both end with Claude building it for you:

- **Quick:** hit Copy, open Claude Code, paste this in, and say the line below.
- **Most reliable** (this one's a build, not a one-line paste, so let Claude read the
  whole thing): hit Download, then tell Claude: *"read ~/Downloads/screenshot-flow-setup.md
  and follow the setup instructions for my OS."*

Either way, say:

> "I'm on [Mac / Windows / Linux]. Set this up for me — the screenshots folder, the native
> capture saving there with a timestamped name, and the hook so you can find a screenshot
> I just took without me pasting it. Then test it with me and explain how to use it."

---

## Instructions for Claude

You are setting up a screenshot-to-file workflow for this user so they never paste images
into the terminal again. Follow these steps in order. Ask before overwriting anything that
already exists, and back up any file you edit.

### Step 1 — Detect the environment
Identify the operating system (macOS, Windows, or Linux) and, on Windows, whether you are
running in PowerShell, Git Bash, or WSL. On Linux, detect X11 vs Wayland and the desktop
environment. Everything below branches on this.

### Step 2 — Screenshots folder + native capture
Goal: the OS's own screenshot hotkey saves every capture as a file with a timestamped name.

- **macOS:** create `~/Screenshots`, then point the native tool at it:
  `defaults write com.apple.screencapture location ~/Screenshots && killall SystemUIServer`.
  macOS already timestamps captures. Cmd+Shift+4 = region, Cmd+Shift+3 = full screen.
- **Windows:** Win+PrintScreen already saves full-screen captures to
  `%USERPROFILE%\Pictures\Screenshots` with timestamped names. For region snips (Win+Shift+S),
  on Windows 11 turn ON Snipping Tool's "Automatically save original screenshots." Windows 10
  lacks that toggle — say so plainly and offer PowerToys or full-screen capture as the fallback.
  In WSL, that folder is `/mnt/c/Users/<name>/Pictures/Screenshots` from your side.
- **Linux:** create `~/Screenshots`. Easiest: point the GNOME/KDE built-in tool there.
  Full setup: install `maim` + `xclip` (X11) or `grim` + `slurp` + `wl-copy` (Wayland) and
  bind a hotkey (e.g. Ctrl+Shift+4) in the desktop's keyboard settings to a small script that
  captures a dragged region, saves it as
  `~/Screenshots/screenshot_$(date +%Y%m%d_%H%M%S).png`, and copies the text
  `Screenshot: <filename> (in ~/Screenshots)` to the clipboard. Write that script, make it
  executable, and walk the user through binding the hotkey (it differs by desktop and usually
  can't be done from the command line).

### Step 3 — The "recent images" hook
Add a `UserPromptSubmit` hook to `~/.claude/settings.json` that lists image files created in
the screenshots folder in the last 5 minutes, newest first, so you can find fresh captures
without the user pasting anything.
- Read the existing settings first and MERGE — never clobber existing hooks. Back it up first.
- Write the hook command for THIS machine: a `find` one-liner on macOS/Linux, a PowerShell
  `Get-ChildItem` version on native Windows, the `/mnt/c/...` path in WSL.
- The injected text must say the list is an index only, and that you read a listed image
  ONLY when the user asks for it in that message — never screenshots they didn't mention.

### Step 4 — The filename-not-path rule (important)
If you set up a clipboard text reference, put the FILENAME on the clipboard with the folder
written in words — for example `Screenshot: screenshot_20260720_141530.png (in the
Screenshots folder)` — never the full file path. Claude Code and similar tools recognize a
file path inside pasted text and re-attach the image as base64, which defeats the purpose. A
bare filename with the folder in words survives as plain text.

### Step 5 — Test it together
Have the user take a region screenshot with their native hotkey, confirm the timestamped file
appeared, then have them type "look at the screenshot I just took" — find it via the hook,
read it, and describe what you see so they get the full effect.

### Step 6 — Explain the workflow
Explain it back in plain words for their OS: which key captures a region, that it saves to
the Screenshots folder automatically, and that they just say "look at the screenshot I just
took" (or "look at my last three screenshots"). Tell them the one habit to break: no more
pasting or drag-and-dropping images into the terminal.

---

*From Connect with Cliff — one honest email a week on what actually worked. connectwithcliff.com*