How to Annotate Screenshots for Claude Code

Claude Code can read images you paste or path in. It cannot read your mind about which of five similar buttons is wrong. Annotation turns a screenshot into instructions.

Vision models interpret pixels; they do not magically know your priority. On a dense settings page, three toggles can look identical at a glance. A number badge and a one-line note remove the coin flip.

A fast path that stays local and works whether you live in the terminal or a GUI wrapper around Claude Code:

• Open the UI state you want fixed (right theme, breakpoint, and data).
• Hotkey Casso and drag numbered boxes over each region.
• Add a short note per box: what is wrong and what good looks like.
• Send. Copy the prompt into Claude Code with the annotated image.
• Ask Claude to change only the referenced regions unless you want a broader pass.
• Re-run the UI, re-annotate only remaining issues, and iterate.

Lead with the goal, then the map: "Match spacing of [2] to [1]. Do not change colors." Avoid burying the request after a long story. One issue per region beats a paragraph that mixes five problems.

Add hard constraints when the codebase is large: "Touch only the component that renders [1]. No drive-by refactors." That keeps Claude from rewriting unrelated layout systems.

When the bug is relational, use two boxes: "[2] should left-align with [1] at 24px gap." Numbers create a shared coordinate system between text and image.

Put location and expected state in the box note. Put project-level context in chat if needed (design system tokens, file paths you already know). Do not restate the entire product history in every mark.

Most failed visual turns share the same mistakes. Avoid these and your first-pass hit rate jumps:

• Huge full-desktop shots with a tiny target and no mark.
• Arrows without numbers when you discuss multiple areas.
• Notes that say "fix this" without expected behavior.
• Uploading sensitive screens to random web tools before the agent.
• Mixing five issues into one box so the model only fixes the first.