Gist

CleanShot screenshots

markdown · November 19, 2026

An agent skill for capturing, annotating, redacting, and exporting macOS screenshots with CleanShot X.

View on GitHub

---
name: cleanshot-screenshots
description: Capture, annotate, redact, and export macOS screenshots with CleanShot X. Use for desktop, window, area, or scrolling screenshots, adding visual callouts to existing images, documenting UI steps, and extracting text from screenshots with CleanShot OCR.
---

# CleanShot screenshots

Use CleanShot X on the Mac that owns the desktop or image. Live capture requires an interactive desktop and macOS screen recording permission. The `action` parameter requires CleanShot X 4.7 or later. If the host provides a required browser or simulator capture tool for the target, capture there and open the saved image in CleanShot.

## Capture or open an image

Bring the requested content into view and capture the smallest area that preserves the context. Run a quoted URL with macOS `open`.

| Task                                           | URL                                                          |
| ---------------------------------------------- | ------------------------------------------------------------ |
| Select an area and open Annotate               | `cleanshot://capture-area?action=annotate`                   |
| Select a window and open Annotate              | `cleanshot://capture-window?action=annotate`                 |
| Capture the screen and open Annotate           | `cleanshot://capture-fullscreen?action=annotate`             |
| Repeat the last area for a matching comparison | `cleanshot://capture-previous-area?action=annotate`          |
| Capture a transient element after a delay      | `cleanshot://self-timer?action=annotate`                     |
| Capture content beyond the viewport            | `cleanshot://scrolling-capture`                              |
| Open a PNG or JPEG                             | `cleanshot://open-annotate?filepath=<encoded-absolute-path>` |
| Edit an image already on the clipboard         | `cleanshot://open-from-clipboard`                            |

For a plain local screenshot, use `action=save` on a capture command that accepts it, then locate the result in CleanShot's configured save folder. For scrolling capture, select the content, finish the capture, and open the result from the Quick Access Overlay. For older versions without the `action` parameter, open Annotate or save from that overlay. The URL API has no output-path parameter for screenshot captures.

For a known rectangle, use `x`, `y`, `width`, and `height` with `capture-area`. Its origin is the selected display's lower-left corner. `display=1` targets the main display. Without `display`, CleanShot uses the display under the pointer. Select the area interactively if you cannot establish the display and coordinates reliably.

```sh
open 'cleanshot://capture-area?x=80&y=100&width=720&height=480&display=1&action=annotate'
```

For an existing file, percent-encode the path as a query value so spaces, ampersands, and other reserved characters survive. With Python 3 available, pass the absolute path as an argument.

```sh
python3 - '/absolute/path/capture & notes.png' <<'PY'
import subprocess
import sys
from urllib.parse import quote, urlencode

query = urlencode({"filepath": sys.argv[1]}, quote_via=quote)
subprocess.run(["open", f"cleanshot://open-annotate?{query}"], check=True)
PY
```

## Annotate and verify

The URL API opens Annotate. Use the editor through available desktop controls to place marks and export the result. If you can launch CleanShot but cannot drive the editor, open the relevant capture mode or image, then give the user the exact marks and export path to apply. A successful `open` only confirms URL dispatch.

- For a walkthrough, place Counter markers beside the controls in action order. Use short text labels for steps that need explanation.
- For a bug report, point an arrow at the symptom and label the observed behavior. Keep nearby UI visible so the reader can find the same state.
- For a single focal point, use Spotlight or an outline. Keep labels clear of the content they describe and check legibility at the final size.
- If sensitive data must be removed, crop it out or cover it with an opaque shape and export a flattened copy. Inspect that copy before sharing. Keep any editable project containing the original pixels local.

Use **Save As** in Annotate to export a PNG at the requested path. If the location is unspecified, save under a descriptive name in the workspace. Save an editable CleanShot project when the user wants to revise the marks. Open the exported image to confirm the target, annotation visibility, and any redactions, then return its absolute path. Use CleanShot Cloud when the user authorizes an upload.

## OCR and recovery

- Use `cleanshot://capture-text` to select text on screen, or pass an encoded PNG/JPEG path via `filepath`. Read the clipboard after recognition completes and verify important text against the source.
- If the URL has no handler, check that CleanShot X is installed on the Mac running the command. If a capture is blank or macOS prompts for access, check CleanShot's permission in Privacy & Security. If the capture is missing from the overlay, try `cleanshot://open-history` on CleanShot X 4.4 or later.

See the [CleanShot URL API](https://cleanshot.com/docs-api) for command parameters and version requirements, and the [CleanShot editor feature list](https://cleanshot.com/features) for available annotation tools.
```sh
npx skills add https://gist.githubusercontent.com/thatbeautifuldream/a9888a6b6b9691d1266e04eb2a9ce34c/raw/cleanshot-screenshots.md
```