Download

How to Give Claude Code a Screenshot (and Codex, Cursor)

Updated 2026-10-05 · by Murilo Prataviera, maker of Aki

You took a screenshot of the broken layout, switched to the terminal, hit Cmd+V, and nothing happened. That's the most common way people hit this, and it isn't your fault: pasting images into a terminal app works differently from pasting text. Below are the methods that actually work, what to do when they don't, and an honest look at when a screenshot is the wrong tool.

Quick answer

  • Yes, Claude Code can see images. It reads PNG, JPEG, GIF and WebP.

  • Paste: copy the image, then press Ctrl+V in Claude Code. On a Mac that means Control, not Command, except in iTerm2, where Cmd+V also works. On Windows and WSL, use Alt+V.

  • Drag: drop the image file into the Claude Code window.

  • Path: type the file path in your prompt, e.g. Look at /Users/me/Desktop/bug.png and fix the overflow.

  • Codex CLI: codex -i screenshot.png "your prompt", or paste into the composer.

  • Cursor: paste with Cmd+V / Ctrl+V or drag the image into the Agent chat input.

Method 1: Paste from the clipboard

This is the fastest option once it works.

  1. Take a screenshot straight to the clipboard. On macOS, press Cmd+Ctrl+Shift+4 and select an area. On Windows, press Win+Shift+S.
  2. Click into the Claude Code prompt.
  3. Press the paste-image shortcut for your platform:
Where you run Claude Code Shortcut
macOS: Terminal.app, Ghostty, most terminals Ctrl+V
macOS: iTerm2 Ctrl+V or Cmd+V
Windows Alt+V
WSL Ctrl+V or Alt+V (use Alt+V if your terminal grabs Ctrl+V)
Linux Ctrl+V

If it works, an [Image #1] chip shows up at the cursor. You can type around it ("the button in [Image #1] overflows on mobile") and refer to several images by number. Later, Cmd+Click (Mac) or Ctrl+Click (Windows/Linux) on an [Image #N] link opens the image in your default viewer.

Why Cmd+V usually fails on a Mac: the terminal grabs Cmd+V for its own text paste, and the clipboard holds an image, not text, so Claude Code never sees the keypress. Ctrl+V gets through to the app, and the app reads the image from the clipboard itself.

Want a different key? Run /keybindings and remap the chat:imagePaste action in ~/.claude/keybindings.json:

{
  "bindings": [
    { "context": "Chat", "bindings": { "ctrl+shift+v": "chat:imagePaste" } }
  ]
}

Bindings that use Cmd only work in terminals that report the Super key (terminals that speak the Kitty keyboard protocol, for example), so stick to Ctrl or Meta if you want it to work everywhere.

Method 2: Drag the file into the window

Drag a screenshot from Finder or your desktop and drop it into the Claude Code window. This skips the clipboard entirely, so it's the go-to fallback when paste doesn't work. Saving screenshots to a file (Cmd+Shift+4 on macOS, without Ctrl) and dragging them in is a reliable habit.

In the VS Code extension's chat panel it works differently: paste the image into the prompt box to attach it. To attach files, hold Shift while you drag them in.

Method 3: Give it the file path

Claude Code can read image files from disk. Just say where the file is:

Analyze this screenshot: /Users/me/Desktop/checkout-bug.png
Why does the total wrap onto two lines?

Paths can be relative or absolute. You can also type @ and pick the file from the path autocomplete. This is the most dependable method of all: no clipboard, no terminal quirks, and it works over SSH as long as the file is on the machine where Claude Code runs.

Troubleshooting: when the image won't go in

Codex CLI and Cursor

Codex CLI. Pass images with the first prompt:

codex -i screenshot.png "Explain this error and suggest the smallest fix"
codex --image before.png,after.png "Compare these states and list the regressions"

For several images, separate the paths with commas or repeat --image. PNG and JPEG are supported. You can also paste an image into the interactive composer. The exact key varies by terminal and platform (there have been separate fixes for macOS, Windows and WSL), so if paste does nothing, --image with a file path always works.

Cursor (editor). In the Agent chat, drag an image file into the input or paste from the clipboard with Cmd+V (Ctrl+V on Windows). Forum reports say drag-and-drop doesn't work in every layout and Ctrl+V paste has had problems on Windows. If one fails, try the other.

Why screenshots are a weak way to tell an agent what to fix

Screenshots are great for "what is this error dialog?" or "make it look like this mockup." They're much weaker for "fix that thing," and here's why:

When the fix lives in the DOM, the agent does better with what's under the pixels: a selector, the element's text, its HTML. Add a cropped image only when the problem really is visual.

A faster option: point at the element (Aki)

That gap is what Aki is for. It's a free-to-use macOS app. You press ⇧⌘A, click the thing that's wrong, write a note, and send it to your coding agent (Claude Code, Codex, Gemini CLI, opencode, Cursor Agent).

Being honest about limits: it's Mac-only (Apple Silicon, macOS 14+), element picking needs a Chromium browser with "Allow JavaScript from Apple Events" turned on, auto-typing into the terminal works with Orca (other terminals read marks via MCP or the CLI), and it's brand new (0.2.0). Marks stay on your Mac. There's no account and no telemetry, though the agent you use will send what it reads to its AI provider.

For a one-off error dialog, paste the screenshot. For "fix this exact element," pointing is quicker and less ambiguous.

FAQ

Can Claude Code see images?

Yes. Claude Code can read screenshots, mockups and diagrams in PNG, JPEG, GIF and WebP. Paste them, drag them in, or reference a file path.

How do I paste an image in Claude Code on a Mac?

Copy the image, then press Ctrl+V (Control, not Command) in the Claude Code prompt. In iTerm2, Cmd+V also works. You'll see an [Image #1] chip when it worked.

Why doesn't Cmd+V paste my screenshot into Claude Code?

Most macOS terminals use Cmd+V for their own text paste, so the keypress never reaches Claude Code. Use Ctrl+V, drag the file in, or type its path.

How do I paste an image in Claude Code on Windows or WSL?

Press Alt+V. On WSL both Ctrl+V and Alt+V are bound, but many terminals grab Ctrl+V, so Alt+V is the safe choice.

How do I give Codex CLI a screenshot?

Run codex -i path/to/screenshot.png "your prompt", or paste the image into the interactive composer. Separate multiple images with commas.

How do I add a screenshot in Cursor?

In the Agent chat, paste with Cmd+V (Ctrl+V on Windows) or drag the image file into the input.

Sources