---
title: "How to annotate a bug screenshot on Mac so your agent fixes the right thing"
description: "Crop, point, label, measure. How to mark up a screenshot on macOS, with the built-in Markup tools or Bigshot's editor, so Claude Code or Codex fixes the thing you meant."
url: https://www.bigshot.pics/blog/annotate-bug-screenshot-mac
---
# How to annotate a bug screenshot on Mac so your agent fixes the right thing

*2026-10-07*


A coding agent looking at an unmarked screenshot has to guess what you mean.
A checkout page has a dozen numbers on it, and "the total is wrong" could
point at any of them. A box, an arrow and three words remove the guess.

![A checkout page in Bigshot's editor: the coupon line is boxed in yellow, the total is circled in red, and an arrow labelled “Total ignores the coupon” points at it.](https://www.bigshot.pics/screenshots/tool-annotate.webp)

## The built-in way: Markup

macOS has basic annotation built in. After a screenshot, click the floating
thumbnail in the corner of the screen to open it in Markup, or open the file
in Preview and click the Markup button. You get shapes, arrows (the line
tool with an arrowhead), text, a highlighter, and crop.

It works for an occasional screenshot. For bug reports it is slower than it
needs to be: the thumbnail disappears after a few seconds, there are no
numbered steps or measurements, and every edit is a few clicks deep.

## What to mark, in order

### 1. Crop to the problem

Crop to the part of the screen that shows the bug, with enough around it to
place it on the page. Less to read means less to misread, and a smaller image
keeps its text sharp when the model scales it down (see
[How big should a screenshot be for Claude?](https://www.bigshot.pics/blog/screenshot-size-for-claude)).

### 2. One problem per screenshot

Three problems on one page are three screenshots. An agent works through an
image with one arrow more reliably than through one with five, and you can
check each fix on its own.

### 3. Point, then label

- **An arrow** at the exact element.
- **A box or an ellipse** when the problem is an area: a misaligned row, a
  cut-off label.
- **Three or four words** beside it: "Total ignores the coupon". The full
  explanation goes in your prompt.

Use one colour that stands out from the interface, such as red on a dark UI.

### 4. Give numbers, not adjectives

"The spacing looks off" is a guess. "The gap is 24 px and should be 16" is a
fix. Measure distances and sizes on the screenshot itself:

![Bigshot's Measure tool: the Pay button labelled 627 × 89, and a ruler across the card labelled 718 px.](https://www.bigshot.pics/screenshots/tool-measure-tile.webp)

Screenshots on a Retina Mac are at twice the size the interface is laid out
in, so divide by two for CSS pixels.

### 5. Number the steps for a flow

For a bug that takes several clicks to reach, number each control in order.
The agent gets the path to the bug, not just where it ends.

![Numbered steps on a checkout form: 1 on the email field, 2 on the card number, 3 on the Pay button.](https://www.bigshot.pics/screenshots/tool-steps-tile.webp)

### 6. Say what the image cannot

Some things are not visible: that it only happens after a coupon, or only in
Safari. Put that in the prompt, or in a note saved with the screenshot.

## In Bigshot's editor

[Bigshot](https://www.bigshot.pics/)'s Capture Editor is built for this. Click a capture's thumbnail
in the island to open it. Every tool has a single-key shortcut:

| Key | Tool | Use it for |
|---|---|---|
| C | Crop | Cut to the problem; press Return to apply |
| A | Arrow | Point at the element; drag its middle to bend it |
| R or O | Rectangle, Circle | Box or ring an area |
| S | Spotlight | Dim everything except the part that matters |
| T | Text | A short label |
| N | Step | Numbered discs, 1, 2, 3, in click order |
| M or ⇧M | Measure | A distance or a size in pixels, copied as you finish |
| I | Colour Picker | The exact colour as HEX, RGB, HSL or OKLCH |
| B | Redact | Pixelate anything private before sharing |

Press ⌘S to save. The file now holds the annotated image; the clipboard
still holds the original capture, so copy or drag the thumbnail again before
you paste. The editor is free.

With a licence and a Project, you can also attach a note to the screenshot
(right-click › **Screenshot Context…**). The note is saved in the
repository's screenshot index, so the agent reads it alongside the image,
even when you ask about it days later. See
[Let your agent find your screenshots](https://www.bigshot.pics/blog/screenshot-context-in-your-repo).

## Checklist

1. Crop to the problem.
2. One problem per screenshot.
3. Arrow or box, plus three words.
4. Measure instead of describing.
5. Number the steps for a flow.
6. Save, then send the saved version.

To hand the result to your agent, see
[How to paste a screenshot into Claude Code](https://www.bigshot.pics/blog/paste-screenshot-into-claude-code)
or [How to give Codex a screenshot](https://www.bigshot.pics/blog/codex-screenshots).