Workflows

Step-by-step recipes for common jobs. Each one links to the reference page for the parts it uses.

Paste a screenshot into a chat or issue

1. Press ⌃⌥A (Area) and drag, or ⌃⌥W to take the frontmost window.
2. The capture is already on the clipboard. Press ⌘V in the chat, issue or document.

To drop the file instead, drag the preview in the bottom-right corner, or a thumbnail from Peek View, into the target app.

Capture a menu, tooltip or hover state

The mouse is busy opening the menu, so use a timer.

1. Press ⌃⌥F to open Capture Frame.
2. Drag its edges over the area, and set the timer to 3 or 5 seconds.
3. Click the shutter, or press ⌃⌥F again.
4. While the outline is red and counting down, open the menu or hover the element.
5. The shot is taken without the frame in it.

The frame remembers its place. Press ⌃⌥F twice for the same shot again. See Capture Frame.

Take the same area several times

Use Capture Frame. After each shot it closes, and ⌃⌥F brings it back at the same position, size and timer. Set the timer to No timer for immediate shots. Useful for before-and-after comparisons and step-by-step screenshots of one panel.

Capture one panel cleanly

1. Choose Smart (⌃⌥S, Licence).
2. Hover. The panel, dialog or card under the pointer is highlighted.
3. Scroll to step out to the region around it if the highlight is too small.
4. Click.

The result needs no cropping. Hold ⌥ while dragging to ignore the edges.

Annotate a bug report

1. Capture the problem.
2. Click its thumbnail to open the editor.
3. Crop to the relevant part and press Return.
4. Line › Arrow to point at the problem. Shape › Rectangle to box it.
5. Text for a short label, then Return.
6. Redact emails, names or tokens.
7. Save (⌘S). The file is overwritten with the annotated image.
8. The clipboard still holds the original. Hover the thumbnail in Expanded View and click Copy, or drag the thumbnail, to send the annotated version.

Document a flow with numbered steps

1. Capture the screen.
2. Open it in the editor and choose Step.
3. Click each control in order. Discs number themselves 1, 2, 3.
4. Optionally Shape › Spotlight around the area that matters to dim the rest.
5. Save.

Check a design: sizes and colours

1. Capture the UI.
2. In the editor, Measure › Distance and drag between two edges. The value, in pixels, is copied to the clipboard as you finish. Hold ⇧ to keep it straight.
3. Measure › Size and drag over an element for its width × height.
4. Colour Picker: hover with the loupe and click to copy the colour as HEX. Switch to RGB, HSL or OKLCH in its card.
5. Close with Cancel (⌘.) if you only wanted the numbers, so the marks are not saved into the image.

Measurements are in screen pixels: on a Retina display, divide by two for points.

Copy text out of a screenshot

1. Open the capture in the editor.
2. Choose Select Text, drag over the text, and press ⌘C. With nothing selected, Copy takes all of it.

Show an agent what is wrong

Let Claude Code or Codex look at your screenshots without pasting them. Needs a Licence.

1. Settings › Projects › Add Project…, and choose the repository.
2. In the plan, keep Add Bigshot instructions to CLAUDE.md or AGENTS.md, Add to .gitignore, and Share captures with agents automatically on. Create the Project.
3. Capture the bug while the Project is active.
4. In the agent, ask: "look at the last screenshot and fix the layout bug".

The agent reads .screenshots/index.json and opens the image. Add a note in Screenshot Context… for anything the screenshot itself does not say. See Projects.

Keep screenshots for one task together

1. On a feature branch, create the Project; it offers a tag named after the branch. Or type a name into New tag in the island's tag pill.
2. Every capture now carries that tag.
3. Ask the agent: "look at the ones tagged checkout".
4. When the work is done, archive the tag in Settings › Projects › Edit › Task tags. The captures keep it and stay searchable.

Approve each screenshot before an agent sees it

1. Set the Project's Sharing to Review first.
2. Captures wait as Needs review.
3. Right-click one, choose Screenshot Context…, check it, and click Share now. Click Exclude for anything that should never be read.

An edited capture needs approval again.

Run an LLM on every capture

1. Settings › General › LLM Connections: make sure Claude Code or Codex shows Connected, or save an API key.
2. Settings › Projects › Edit › Add Hook. Pick the connection, access and timeout, and write the prompt.
3. Capture with the Project active. Right-click the capture › View Hook Runs… to see the result.

Use Pause Hooks in the menu bar to stop new runs while you take a burst of screenshots. See Hooks.

Find an old screenshot

1. Press ⌃⌥O to open the Library.
2. Type in the search field: words from a note, a tag, the source app, or text on screen (with OCR on).
3. Space to Quick Look, Return to edit, or drag it out.

Export a batch

1. In the Library, select captures: ⇧-click for a range, ⌘-click to add, or ⌘A.
2. Click Export… and pick a folder. Nothing there is overwritten.

Or Share for AirDrop, Mail and Messages.

Keep the Desktop tidy

1. Settings › General › Keep screenshots: choose 1 day or 1 week.
2. Old captures are moved to the Trash automatically.
3. For any you want to keep, right-click › Keep · prevent automatic deletion.

Replace the macOS screenshot keys

1. System Settings › Keyboard › Keyboard Shortcuts › Screenshots: turn off ⇧⌘3, ⇧⌘4 and ⌃⇧⌘4.
2. Bigshot Settings › Shortcuts: turn on Use ⇧⌘3 and ⇧⌘4 for Bigshot.

⇧⌘3 now takes the display, ⇧⌘4 and ⌃⇧⌘4 an area. ⇧⌘5 stays with macOS.