Guide · Updated July 2026
Show Your Coding Agent What's Wrong
If you've ever typed "no, the OTHER red box" at a coding agent, you already know the thesis of this guide: describing visual bugs in prose is the slowest, least reliable way to get them fixed. The fix is not better descriptions. It's showing instead of telling — a marked-up screenshot plus a line or two of intent beats paragraphs of careful prose, on the first pass, almost every time.
That's not a style preference. It follows from what agents can and can't see. Modern coding agents read images well — a circled element on a screenshot lands as precisely as a file path. What they can't do is see your screen unless you put it in front of them. This guide covers both halves: how to capture visual context that actually works, and where the seeing gap still is.
Why prose fails for visual bugs
Words are ambiguous pointers at pixels. You know exactly which element you mean; the agent has to reconstruct it from a sentence, against a render it has never seen:
| What you type | What the agent has to guess |
|---|---|
| "The red box is misaligned" | Which of four red-ish elements, and misaligned relative to what |
| "The spacing looks off on the profile screen" | Which gap, which direction, off by how much |
| "The button doesn't look right on mobile" | Which button, which device size, what "right" looks like |
| "The text gets cut off sometimes" | Which text, and which state makes it overflow |
Every wrong guess costs a full round trip: the agent edits the wrong element, you rebuild, you look, you re-describe with more adjectives. Two or three loops of that and you've entered the infinite frustration loop — you spend more time describing than the agent spends coding. It's the single biggest time leak in the screenshot-to-fix loop, and it's entirely avoidable.
What your agent can and can't see
The uncomfortable context behind all of this — the agent that wrote your UI has never seen it:
| Context | Can your agent see it? |
|---|---|
| Your code | Yes — the one thing it sees perfectly |
| Logs, stack traces, terminal output | Yes, when they run where the agent can read them |
| Your web app, rendered | Increasingly yes — agents drive browsers, screenshot pages, inspect the DOM |
| A screenshot you provide | Yes — vision-capable agents read images well, including your markup |
| Your mobile app, running on a phone | No. It will never see that screen unless you show it |
For web apps the gap is closing fast: browser-driving agents screenshot their own output and verify their own fixes. For your iOS or Android app there's no browser to drive — the agent writes UI code, and it ships blind. Every visual bug in your mobile app exists only on your screen until you carry it across. That's why visual context isn't a nice-to-have on mobile; it's the whole channel.
How to capture visual context that works
Six rules, in priority order:
- One bug per capture. A screenshot with five problems circled gets five shallow fixes and a restyled screen. Serialize.
- Mark it up. Circle the exact element. A circle is unambiguous where a sentence never is — this single habit kills "no, the OTHER red box" dead.
- Show intent, not just error. An arrow to where the element should sit, or a one-line note, tells the agent the target state. Expected vs actual, drawn instead of written.
- Include the state. What you tapped to get here, what account or data was loaded. Half of "unreproducible" visual bugs are just unstated state.
- Paste error text verbatim. If there's a message on screen or in the logs, the exact string is searchable in the codebase. Your paraphrase isn't.
- Demand proof back. Ask for a before/after — a re-render, a test, a screenshot. An agent that must show the fix is far less likely to claim one.
And the template that carries those rules — paste it alongside every screenshot you hand to Claude Code, Codex, or Cursor:
Attached: a screenshot of a visual bug. The broken element is
circled.
What's wrong: [one sentence — "the circled button overlaps the
tab bar"]
Where: [screen / route / component name, if known]
How I got here: [the taps or steps that produced this state]
Expected: [one sentence — what this should look like instead]
Error text, if any: [verbatim]
Fix only the circled issue. Do not restyle or refactor anything
else on this screen. When you're done, tell me exactly what
changed and how to verify it.
The "fix only the circled issue" line matters as much as the screenshot. Agents restructure surrounding code while fixing the thing you asked for — silent rewrites — and a tight scope line is the cheapest guard against a vibe coded mess spreading from a one-line fix.
Markup beats model roulette
The current folk wisdom for visual bugs is model routing — people swear by one model "for fixing bad UI" and switch agents when a layout fight drags on. Model choice is real, but it's the smaller lever. A mid model with a circled screenshot and a scoped prompt beats the best model with a paragraph of adjectives, because the failure mode was never reasoning — it was aim. Fix the aim first; then argue about models.
Closing the mobile gap
On web, the agent can be its own camera. On mobile, you are the camera — and the pipeline: screenshot on the phone, transfer to the laptop, open an editor to draw the circle, paste, type the context. It works, and it's exactly the manual carry described in the screenshot-to-fix loop.
Vibejar makes the phone side native. Capture inside your own iOS or Android app, circle the problem on the device, and your agent picks it up with the screenshot, markup, and context attached — then sends back before/after proof so you're not eyeballing fixes either. It's the show-don't-tell workflow from this guide with the carry removed, for $88 one time. For the wider practice of debugging AI-built apps, start with vibe debugging; for what to write when a human needs the report instead, see the bug report template.
Frequently asked questions
Can Claude Code, Codex, and Cursor see screenshots?
Yes. All the major coding agents accept images, and their vision is good enough to read layouts, error text, and your markup. A circled element on a screenshot is treated as precisely as a named file. What they can't do is take the screenshot of your running mobile app themselves — capture is on you.
What's the best way to describe a UI bug to an AI agent?
Mostly, don't describe it — show it. One screenshot, the broken element circled, plus three short lines: what's wrong, how you got there, what you expected. Reserve prose for what pixels can't say (the trigger and the intent), and paste any error text verbatim.
Why can't my agent see my mobile app?
Web agents can drive a browser, so they can render and screenshot your web app. There's no equivalent for an app running on a phone — no DOM, no page to load. Some setups let an agent drive a simulator, but the app on the actual device in your hand is a screen the agent never sees. It ships UI blind, which is why every mobile visual bug has to be carried to it.
Do marked-up screenshots really change agent output?
Noticeably. The most common failure with visual bugs isn't a bad fix — it's a correct fix applied to the wrong element, which costs a full describe-rebuild-look round trip. Markup removes the guess, so first-pass fixes land far more often, and the scope line ("fix only the circled issue") keeps the fix from turning into a rewrite.