Omniscio

OmniscioGuidesImages and screenshots

Claude Code images: paste a screenshot or give a path

A screenshot of the broken layout, a design mockup, an architecture diagram: some context is a picture, and describing it in words costs more than sending it.

This page covers the three ways to add an image, the formats and limits, the prompts that get useful work back, and where pasted images go. A paste that produces nothing is a different problem, and the copy and paste guide owns it.

Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .

Three ways to add an image

Anthropic lists exactly three, and they differ in what they need from you rather than in what Claude gets.

  1. Drag and drop. Drag the image file onto the Claude Code window. Nothing to type.
  2. Paste. Copy an image and paste it with Ctrl+V, or Alt+V on Windows and WSL. The key is bound to a rebindable action if the default clashes with your terminal.
  3. Give the path. Write the request with the file in it: Analyze this image: /path/to/your/image.png. Claude reads the file with its Read tool.

The path route is the one that survives context you cannot control: a remote session, a scripted run, a file the clipboard never held. It is also the route that respects a permission rule, because a pasted image path is treated as a file read.

Source: "Work with images" in Common workflows and the Read tool entry in the tools reference, read November 18, 2026.

What to ask once it is in

An image with no question gets a description. An image with a task gets work. Anthropic's examples are worth copying because each names the outcome:

  • Describe the UI elements in this screenshot for a design that needs breaking into components.
  • Here's a screenshot of the error. What's causing it? for a message you cannot copy as text.
  • Generate CSS to match this design mockup when the target is code rather than an opinion.
  • Are there any problematic elements in this diagram? when you want a critique.

Say where the image came from and what you want to happen next. A screenshot of a test failure inside a repository is stronger than the same screenshot alone, because Claude can open the test file it names.

Sources: the example requests in "Work with images" in Common workflows, read November 18, 2026.

Formats, size and what Claude actually sees

Claude Code returns PNG, JPEG, GIF and WebP files to Claude as visual content rather than raw bytes. Anything else is an ordinary file: read as text, or refused if it is binary.

The size limit that bites is the model's, not a file cap. Anthropic says Claude Code resizes and recompresses large images to fit the model's image size limits before sending them, so Claude may be looking at a downscaled copy of your 4K screenshot.

That is the explanation for a frustrating failure mode: Claude misses fine detail in a big image. The fix Anthropic gives is to crop the region you care about, for example with ImageMagick through Bash, and read the crop.

The file ceiling is far higher: the Read tool refuses an image larger than 128 MB outright, which a screen capture never reaches. Treat the downscale as the limit you plan around.

Source: the Images section of the Read tool in Anthropic's tools reference, read November 18, 2026.

Several images in one conversation

One conversation can hold more than one image, and Anthropic lists that as a supported way to work. Screenshots, diagrams and mockups are all named as the kind of picture it handles.

Each one becomes a numbered reference. In the terminal, Cmd+Click on macOS or Ctrl+Click on Windows and Linux opens the original in your viewer, which is the fastest way to check that Claude is looking at the picture you meant.

The practical pattern is before and after: the broken screenshot and the design it should match, in one message, with the difference as the question.

Source: the tips under "Work with images" in Common workflows, read November 18, 2026.

Where attached images go

Images you paste or attach are stored under Claude Code's own temporary directory rather than under ~/.claude, according to Anthropic's description of what sits outside it.

That is worth knowing for two reasons. Nothing appears in your repository, so a pasted screenshot never shows up in a commit. And cleanup can remove them, so an image you need to keep belongs in the project, not only in a conversation.

Source: the transcript and attachment storage rows of Explore the .claude directory, read November 18, 2026.

Limits and what they mean

  • Fine detail in a large image is lost. Crop before you ask about a specific pixel-level difference.
  • The format set is fixed. PNG, JPEG, GIF and WebP. Convert anything else first.
  • Downscaling is the limit you plan around. The 128 MB refusal on a single file is the outer ceiling, far above a normal screenshot.
  • A permission rule can leave the image out. A Read deny rule matching a pasted image's path stops Claude Code attaching it.
  • Images accumulate. A long conversation with many screenshots can push a request past the size limit, which Anthropic's error reference answers with /compact.

The last one has a documented escape. When accumulated images push a request past the size limit, Anthropic's error reference says to run /compact, which drops accumulated images and attachments. The context window guide covers what else fills it.

Common mistakes

  • Typing a path and expecting an attachment. The path route works because Claude reads the file, so the request has to actually name it and ask.
  • Sending a full-page screenshot and asking about one button. Crop to the region, or the detail may be resized away.
  • Using a format outside the four. A HEIC screenshot from a phone is not one of them; convert it first.
  • Assuming the paste problem is an image problem. If the image never attaches, that is the copy and paste guide, not this one.
  • Asking "what is this" and stopping. Name the outcome — the fix, the CSS, the component list.

Where these answers come from

Common questions

Can Claude edit the image, or only read it?

These routes are for reading. Claude can write files and run tools, but the documented image support is about seeing one, not editing pixels.

Does a screenshot count against my context?

Yes, and a large one costs more than a cropped one. Drop images you no longer need with /compact.

Which paste key on a Mac?

Ctrl+V generally, and Cmd+V in iTerm2. On Windows and WSL it is Alt+V, because Ctrl+V belongs to the terminal there.

Can Claude see a PDF the same way?

PDFs are read as documents rather than images, in page ranges when they are long, and they need pdftoppm from poppler-utils for a range read.