Paste screenshots into Claude Code with Ctrl+V (and why some silently vanish)

TL;DR Copy any screenshot and paste it straight into the Claude Code prompt with Ctrl+V. In iTerm2 (macOS), Cmd+V works too; on Windows and WSL, use Alt+V. An [Image #1] chip drops in at your cursor and you name it inside the sentence: "fix the margin in [Image #1]". If you paste and nothing shows up, it's not you: image paste fails intermittently and gives no error. When it does, drag the file onto the terminal or hand Claude the path.

To give Claude Code an image, most people do the same dance: take a screenshot, save it to the desktop, drag the file in or type out the path. Almost all of that is unnecessary. Copy the screenshot to your clipboard and paste it straight into the prompt with Ctrl+V. Claude Code drops an [Image #1] chip right where your cursor is and treats that image like any file you'd hand it.

The right key for your terminal

This is where a lot of people give up too early: they try Ctrl+V, nothing happens, and they assume the feature isn't there. The problem is almost always the key, and it depends on the terminal.

On WSL both are bound, Ctrl+V and Alt+V. If your terminal grabs Ctrl+V for its own paste, use Alt+V and the image gets through anyway.

In iTerm2, Cmd+V works, but Ctrl+V tends to be more reliable. If a screenshot won't go in with Cmd+V, try Ctrl+V before giving up.

The [Image #N] chip and how you name it

When you paste, you don't see the image inside the terminal. You see a text chip, [Image #1], at the cursor position. That's your handle: you write around it and name it inside the instruction.

Here's the final design: [Image #1]. Adjust the header spacing
in @src/components/Header.tsx to match it.

You can paste several screenshots in the same conversation ([Image #1], [Image #2]...) and point at each one by its number. When Claude cites one back in its reply, Cmd+Click (Mac) or Ctrl+Click (Windows/Linux) the [Image #1] link to open it in your default viewer.

When you paste and nothing shows up

Here's the part nobody tells you, the one that saves you half an hour of frustration: image paste is intermittent. Sometimes you paste, no chip appears, the prompt stays empty, and there's no error. The image got lost somewhere between the clipboard and the CLI, and you keep typing without realizing it.

It hits Cmd+V in iTerm2 hardest (there are several open bugs in the repo), and in some setups it stops working after the first message. What to do when it fails:

1. Click the prompt field before pasting. It bumps the hit rate a lot.
2. If it still won't go in, don't fight it: drag the image file onto the terminal window. That's the most reliable method.
3. Or hand Claude the path directly: Analyze this image: /path/to/your/screenshot.png. Works on every platform, every time.

Pasting a screenshot is just one of the five ways to give Claude Code context. It's the most direct one for anything visual, and now you know why it sometimes doesn't land.

Reference

Official docs: Work with images