← Blog

How to paste a screenshot into Claude Code — and how to never need to again

6 min readMilind Soni

You copied a screenshot, pressed Cmd+V in Claude Code, and got nothing — or a stray filename instead of the image. Nothing is broken; you're using the wrong modifier key, and Claude Code's own docs are quietly explicit about which one is right.

To paste a screenshot into Claude Code on macOS, press Ctrl+V, not Cmd+V. Cmd+V belongs to the terminal, which pastes text only; Ctrl+V reaches Claude Code, which reads the image off the clipboard and attaches it as [Image #1].

Here's the whole picture: the paste shortcut, the capture shortcut that skips the file dialog, the fallbacks for when paste physically can't work, the same trick for Codex, and — once you're tired of the loop — how to stop pasting screenshots at all.

The 10-second answer

Press Ctrl+V. On every platform, including macOS. The official Claude Code docs list three ways to add an image and put the warning right in the instructions: "Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v)."

When it lands, the composer shows a placeholder like [Image #1] and the image ships with your next message. You can Cmd+Click the placeholder later to reopen the image in your default viewer. If Ctrl+V does nothing, your clipboard probably holds a file reference rather than pixel data — many screenshot tools copy a path, not an image. The next section fixes that at the source.

Capture straight to clipboard

macOS screenshots default to files on your Desktop. Adding Ctrl to the shortcut sends the capture to the clipboard instead: press Cmd+Shift+Ctrl+4, drag out a region, then Ctrl+V in Claude Code. Two keystrokes, zero files on your Desktop. (Apple's full shortcut list.)

Crop tight while you're at it. Claude bills roughly (width × height) / 750 tokens per image and works best under ~1,568 px on the long edge, per the vision docs. An 800×500 crop of the broken component costs about 533 tokens; a full Retina screen, even after downscaling to the 1,568 px limit, costs around 2,100 — four times the price, mostly for pixels the model doesn't need.

The file-path method

Two more methods that never depend on clipboard plumbing:

  • Drag the file in. Drop an image onto the Claude Code window and it's attached. In VS Code's integrated terminal, hold Shift while dropping — otherwise VS Code opens the file in an editor tab instead.
  • Type the path. Analyze this image: /Users/you/Desktop/bug.png — Claude Code reads image files from disk like any other file. This also works in scripts and claude -p runs.

Paths are the most portable option: they survive tmux, every terminal emulator, and SSH (as long as the file is on the machine Claude Code runs on), because no clipboard is involved.

When paste fails

Two environments genuinely can't do clipboard-image paste today:

  • SSH sessions. Your clipboard lives on your local machine; Claude Code is running on the remote one, and there's no channel carrying image data between them. The issue tracking this (anthropics/claude-code#5277) is still open. Workaround: save the screenshot to a file, scp it over, and pass the remote path.
  • VS Code's integrated terminal on Windows/WSL. Ctrl+V does nothing or pastes text (anthropics/claude-code#22377, closed as a duplicate of a long line of similar reports) — the terminal consumes the keystroke before Claude Code sees it. Use Shift+drag or a file path instead.

When in doubt, fall back to the path method above. It has no failure modes worth writing a blog post about.

Codex has the same trap, plus a flag

OpenAI's Codex CLI mirrors the quirk — in the interactive TUI on macOS it's Ctrl+V there too — and clipboard paste has its own trail of bug reports (openai/codex#2743, openai/codex#15612). The dependable route is the -i / --image flag, which attaches files to the initial prompt, comma-separated or repeated:

codex -i mockup.png,error.png "Make the implementation match the mockup"
codex exec -i before.png "Why does the modal clip at small widths?"

For the capture side of the Codex workflow — getting good app screenshots to feed that flag — see our guide to Codex screenshots.

The six-actions-per-screenshot problem

Now count the loop you just optimized: hit the capture shortcut, drag the region, switch to the terminal, Ctrl+V, type a sentence explaining where in the image to look, press Enter. The manual loop is ~6 actions per screenshot; an MCP capture is zero. In a visual debugging session where every iteration needs fresh eyes, that's the difference between staying in flow and moonlighting as a screenshot courier.

The escape ladder has two rungs. First, let the agent take its own screenshots with an MCP tool like Peekaboo or macos-use — you stop capturing, but you still type the paragraph describing where to look. Second, capture that carries its own pointing — what we call spatial context. We build SupaMaus Lite for this: hold Control+Option and move your cursor over the thing you mean, and the capture lands in Claude Code as an annotated screenshot plus the window's accessibility text — the gesture is the "where to look," so there's nothing to paste and nothing to describe.

claude mcp add --transport http supamaus http://127.0.0.1:19741/mcp

(The app's install script runs this with the auth token filled in, and configures Codex the same way.) It's all local — an on-device MCP server, no API keys.

FAQ

Why doesn't Cmd+V work for images in Claude Code? Because Cmd+V never reaches Claude Code. Terminal emulators own the Cmd-key shortcuts and implement paste as "insert clipboard text" — an image on the clipboard has no text representation, so nothing useful arrives. Ctrl+V passes through to Claude Code itself, which checks the clipboard for image data and attaches what it finds.

Can Claude Code take its own screenshots? Yes, two ways. The built-in computer use research preview (macOS, March 2026) lets Claude capture and interact with your screen under per-app approvals. Or add a screenshot MCP server so captures become a tool call instead of a chore — the trade-offs are covered in giving Claude Code eyes.

How do I screenshot the iOS Simulator for Claude? Press Cmd+S in the Simulator to save a screenshot, or script it with xcrun simctl io booted screenshot /tmp/sim.png, then give Claude Code the path. If you point at Simulator UI a lot, note that the Simulator bridges your app's accessibility elements into the macOS accessibility tree — so gesture-based capture tools like SupaMaus Lite can resolve the exact element you're pointing at, down to your own accessibilityIdentifier.