Show it the screen

What it is and why it matters

Claude Code writes the code, but on its own it doesn't see what you see. If it has no way to look at the page, the crooked button or the form that won't submit don't exist for it. And in the end you're the one who finds them, after it has told you “done.”

This guide fixes the problem in both directions. You show Claude the screen, with a screenshot. And Claude looks at the screen by itself, with a browser it can use: it opens the page, clicks, fills in, looks at the result.

It matters because a visual bug explained in words is slow and vague. “The button is a bit lower” can mean ten different things; an image can't. And when Claude walks through the flow itself, it finds and fixes the most basic bugs before they reach you.

The general rule, no “done” without proof, I've already explained in another guide. Here I focus on the visual part: how Claude sees the page and how it shows you that it works.

1. The sentence to give Claude

This is the sentence I use. I paste it after asking for a change, or I put it in CLAUDE.md once and for all. Copy it as is:

After every change, open the page in the browser and go through the flow yourself like a real user: click, fill in, submit. Take a screenshot before and one after. Then tell me what you saw, step by step. Don't write "done" until you've seen it work: attach the screenshots as proof. If something doesn't add up, fix it and check again.

Every part has a reason:

• “Go through the flow yourself like a real user”: opening the page isn't enough. It has to do what a person would do, in the same order.
• “A screenshot before and one after”: the comparison shows what actually changed, not just that the page loads.
• “Tell me what you saw, step by step”: if a step is missing from the account, it probably didn't do it.
• “If something doesn't add up, fix it and check again”: that way it does the round of fixes, not you.

The sentence only works if Claude has a browser to use. Without one, it can't open anything: section 3 shows how to give it one. And if it can't open the page, it has to tell you, not write “done” anyway.

Put it in CLAUDE.md

CLAUDE.md is the project's instruction file. It lives in the main folder, as CLAUDE.md or .claude/CLAUDE.md, and Claude Code reads it at the start of every session. If you put the sentence there, you don't have to repeat it every time. You can have Claude add it itself:

Add this rule to CLAUDE.md for every change to the interface: [paste the sentence here]

Then open a new session: the file is loaded at startup. To check that it picked it up, type /context and look under Memory files.

2. Show it the screen yourself

Sometimes you spot the problem before it does. Instead of describing it, send it the image. In Claude Code you have four ways:

1. In the terminal: copy the image and paste it with Ctrl+V. On a Mac it's Ctrl in Terminal too, not Cmd (in iTerm2 Cmd+V works as well). On Windows it's Alt+V. [Image #1] appears in your message.
2. Or drag the image file into the Claude Code window.
3. Or write the file's path in your message, like in the prompt below.
4. In the desktop app: the + button next to the message box to attach the file, or drag the image into the box.

look at this screenshot: /path/to/image.png

Then one line is enough. [Image #1] tells Claude which image you mean, useful when you paste more than one in the same conversation.

[Image #1] this button is crooked, fix it

To take a screenshot of part of the screen: on a Mac, Cmd+Ctrl+Shift+4 copies it straight to the clipboard; on Windows, Win+Shift+S. That way it's ready to paste.

3. Give Claude a browser

For Claude to go through the flow by itself, it has to be able to open the page. There are two ways, depending on where you use it.

The desktop app: the built-in browser

In the Claude desktop app, in the Code tab, there's a Browser pane. You open it with the Browser button in the session's top bar, or with Cmd+Shift+B on a Mac (Ctrl+Shift+B on Windows). Claude starts your site locally, opens it there, clicks, fills in forms, takes screenshots and fixes what it finds. And you watch it while it does.

There's also an option, Auto-verify changes, which is on by default: after editing files, Claude checks by itself with screenshots and errors before finishing its reply. The sentence from section 1 is still useful: it asks for the user's full flow and an account of what it saw.

The terminal: Claude in Chrome

If you use Claude Code in the terminal, the way is Claude in Chrome: an extension for Chrome or Edge, which also works with other Chromium-based browsers. You install the extension from the Chrome Web Store, then start Claude Code like this:

claude --chrome

Inside the session, /chrome shows you whether the connection works and lets you pick Enabled by default, so future sessions start already connected. I only turn it on when I need it, because with the browser always on, the tools take up space in the context. You need a paid Claude plan (Pro, Max, Team or Enterprise), signed in through /login: with just an API key it won't turn on.

Here Claude uses your real browser, in a window you can see, including pages where you're already logged in. If it hits a login page or a CAPTCHA, it stops and asks you. It can also read errors in the console, useful when the page looks fine but something underneath is wrong.

Screenshots as proof

If you want to open the screenshots Claude takes in the browser yourself, ask it to save them to files: it tells you the path and you look at them whenever you like.

Save the before and after screenshots in a project folder and tell me the paths.

If you build iPhone apps

The browser is for websites and web apps. For an iOS app, the desktop app on the Mac has an iOS Simulator pane, in beta: Claude builds the app, launches it in the simulator, taps through the screens and reads them to verify its changes. You need Xcode installed, and it only works with simulated devices, not a real iPhone.

Common mistakes

• Describing a visual bug in words. Paste the screenshot and add one line: it's faster and leaves no doubt.
• Giving Claude the sentence without giving it a browser. Open the Browser pane in the desktop app or start Claude Code with claude --chrome, otherwise it has nothing to look at.
• Accepting “I checked” without images. Ask for the before and after screenshots: if there are none, the check didn't happen.
• Stopping at the first screen. Check that Claude's account goes all the way to the end of the flow, up to the submit.

Checklist

• The sentence is in the project's CLAUDE.md
• I opened a new session after adding it
• Claude has a browser: the Browser pane or claude --chrome
• I know how to paste a screenshot (Ctrl+V, Alt+V on Windows)
• Every “done” comes with a before and an after screenshot
• Claude's account covers the whole flow

Frequently asked questions