Claude Code Add Screenshot: Step-by-Step Tutorial

Claude Code add screenshot is the act of putting a picture of the UI into the same session that can edit your repo. In 2026 that is useful for layout color and spacing. It is not a name. The model still guesses which button you meant.

Most tutorials stop at "drop the PNG." This one walks a real bug twice: once as pixels, once as a named Accessibility hit.

The pixel page is Claude Code screenshots. Token cost is screenshots waste Claude Code tokens. Screen access is can Claude Code see my screen.

What does Claude Code add screenshot actually do?

It attaches image bytes to the prompt. Claude Code can describe what it sees. It cannot read the Accessibility tree of the window you are looking at unless a tool does that job.

It does not grant always-on screen share. You added a file. That is all.

A screenshot is evidence. It is not an element id.

A real example, start to finish

The settings dialog has two Save buttons. One is in a footer. One is inside an "Advanced" disclosure. Users click the footer. The advanced toggle never persists.

1. Open the repo in Claude Code. Run the Mac app or the staging site the user way.

2. Reproduce the bug. Open Settings. Expand Advanced. Flip the toggle. Click the footer Save.

3. Capture a PNG the way you already do. CleanShot X is fine. Shift-Command-4 is fine.

4. Add the screenshot to Claude Code. Ask one sentence: the Advanced toggle does not persist when I click the footer Save.

5. Watch the first patch. It often edits the wrong Save handler because both buttons look blue.

6. Leave that chat. Do not keep stacking PNGs.

7. Install PinVari. Grant Accessibility. Connect Claude Code with one click, or claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp". The connector talks to 127.0.0.1:3402.

8. Hold Option-Command-A. Circle the Advanced Save, not the footer. Speak: persist the Advanced toggle when this Save is clicked.

9. Ask Claude Code to take pinvari_next_instruction. Review the handler it opens. Reload. Click the same path.

That is the tutorial. The screenshot found the dialog. The named mark found the control.

When should I still add a screenshot?

Color and spacing

Type: visual polish.

Capture: PNG.

Resolution: "this gap is 8px too tall" is a pixel job.

Named interaction

Type: which control.

Capture: PinVari mark.

Resolution: role, label, frame, confidence, crop, spoken words.

Mixed ticket

Type: both.

Capture: one mark, then one PNG if color still matters.

Resolution: do not paste three full-window shots.

I do not quote Claude plan prices. PinVari is 39 dollars one-time at PinVari pricing.

How do people add a screenshot in practice?

Drag the file into the Claude Code session. Paste from the clipboard if your build supports it. Attach from the file picker.

I will not invent a version pin or a hidden flag. If paste fails, write the file to disk and attach that path.

One picture per turn. A collage of five dialogs is how the model describes the wrong one.

The Claude Code tutorial covers the rest of the CLI. This page stays on pictures versus names.

What should I skip?

Skip pasting a 5x retina full-screen capture of an ultrawide. You will learn why screenshots waste tokens.

Skip redacting after you sent it. Crop first.

Skip using a screenshot as a substitute for "can Claude see my screen." It cannot, not as a live feed, unless you add a computer-use or capture tool.

Skip Jam.dev if the bug is in a native window. Console in a Chromium tab is a different capture.

CleanShot X stays for marketing shots. It does not emit an AX label.

What if the screenshot looks right and the patch is still wrong?

The picture showed a blue button. The tree had four buttons. The model picked the first.

Ask the agent to call pinvari_request_capture. The notch island lights up. Circle the one you mean.

If AX is a bare group, PinVari can retry after AXManualAccessibility and fall back to on-device OCR. Write that on the ticket.

Dwell of about 0.2 seconds can resolve a control without a circle. I still circle in this tutorial. The lime trail is a receipt.

Ask, never guess. That is for you when you paste, and for the agent when confidence is below 0.8.

Voice-only is Option-Command-V. Pause is Option-Command-P. Marks keep frames when you scroll.

Full focused-window text goes up to 40,000 characters, including text scrolled out of view. Use that when the bug is copy.

A checklist you can copy

Add screenshot, then name
[ ] Repo open in Claude Code
[ ] Bug reproduced the user way
[ ] One cropped PNG attached
[ ] One sentence, not a novel
[ ] First patch reviewed
[ ] PinVari on 127.0.0.1:3402
[ ] Option-Command-A on the real control
[ ] pinvari_next_instruction reviewed
[ ] Reload the same path

If you stop after the PNG, you stopped at a guess.

FAQ

Can Claude Code see my screen without a screenshot?

Not as a live desktop. You add a picture, or you add a tool that reads the window. PinVari is the local tool path.

Does adding a screenshot upload my whole disk?

It uploads the image you attached, on whatever path your Claude Code account already uses. Crop secrets first.

Should I add a screenshot and a PinVari mark in the same turn?

Only if color still matters after the name exists. The mark should lead.

Does PinVari replace screenshots?

For "which control," yes. For pixel-perfect marketing, no. Keep CleanShot X for that.

Why is the hotkey Option-Command-A?

That is the PinVari capture chord. Option-Command-V is voice-only. Option-Command-P pauses a long page.

What mistakes burn a screenshot-first week?

The first is attaching the whole desktop. Crop to the dialog.

The second is describing the picture in five paragraphs. The picture is already there. Add one sentence.

The third is stacking new screenshots when the first patch missed. Name the control instead.

The fourth is granting every MCP server because one picture was not enough. Add PinVari. Call one tool.

The fifth is filing GitHub with only the PNG. The next person cannot search a label that was never captured.

Name the control. "The blue Save" is two Saves on this dialog.

When the agent asks you to point mid-task, do it. Text follow-ups drift.

PinVari supports Intel and Apple Silicon on macOS 14+. The notarized Developer-ID DMG can do the global hotkey.

Keep captures organized by app in the Command Center. Crash-safe recovery exists. Finish the mark before you reboot.

Write the breakpoint if the bug is layout. Write the URL if it is a page. PinVari can read the real browser URL from the AX web area. Still say staging or production.

Selected text is part of spatial context. If you highlighted a string, say so.

Interactive-element maps help the agent see siblings. You still circle the one you care about.

Deictic words bind to the pointer trail. "This" means the element under the pointer when you said it.

Multi-display marks remember the monitor. If settings is on the laptop, say so.

I do not name every vendor. Cursor can take a Cursor screenshot too. The same rule applies: pixels then a name.

If a teammate uses Wispr Flow for email, keep it there. Use PinVari when words must bind to a control.

Teams later add hooks and skills. You do not need those to finish this tutorial. You need one PNG, one mark, and a reviewed handler.

That is Claude Code add screenshot in 2026: attach the picture if you must, then replace the guess with a named mark on 127.0.0.1:3402.