Screencoord

A command line tool for picking screen rectangles. Drag a region on any display, adjust it with resize handles, and get coordinates ready for screencapture -R, CleanShot-style URL handlers, or AppleScript window math — printed to stdout and copied to the clipboard.

Current version: 0.1.0

I write a lot of scripts that need an exact screen rect, and measuring by eye (or with a color picker) gets old fast. screencoord puts a dimmed overlay on every display, lets you drag and fine-tune a selection, then hands back a single coordinate string.

Installation

Via Homebrew

brew tap ttscoff/thelab
brew install screencoord

No Xcode required — the formula installs a prebuilt universal macOS binary from GitHub Releases.

Manual download

Grab the latest universal binary from the GitHub releases page.

Build from source

Requires Swift (Xcode or Command Line Tools):

git clone https://github.com/ttscoff/screencoord.git
cd screencoord
swift build -c release
cp .build/release/screencoord /usr/local/bin/

Usage

Default format is for screencapture -R (x,y,w,h in screen points):

screencapture -R "$(screencoord)" output.png

AppleScript list literal:

screencoord --format applescript

Help:

screencoord --help

On success, the same string is written to stdout and the clipboard. Cancel (Esc or Cancel) leaves the clipboard unchanged.

While selecting:

  • Drag to create the rectangle; release to enter edit mode
  • Corner and mid-edge handles resize; drag inside the rect to move
  • Live W×H readout uses units for the active --format
  • Return / Confirm commits; Esc / Cancel aborts
  • Confirm is ignored until the rect is at least 10×10 points

Formats

Format Output Use with
screencapture (default) 100,200,800,600 screencapture -R
applescript {100, 200, 800, 600} AppleScript screen math

Both formats describe the same rectangle in screen points (top-left origin at the primary display). Only the string shape differs. screencapture -R takes points, so Retina selections are not scaled by the backing factor.

Multiple displays

Multi-display support is implemented but not fully tested yet. The overlay covers every screen and keeps a selection on one display at a time; secondary-display capture has not had thorough real-world verification.

screencapture -R uses one global point space for the whole desktop arrangement:

  • Origin (0,0) is the top-left of the primary display
  • A display to the right of primary has x past the primary width (for example 1920,100,800,600)
  • A display to the left of primary uses a negative x (for example -800,100,800,600)
  • Displays above/below primary shift y the same way (negative when above)

So a rect on a secondary monitor is still one x,y,w,h string — no separate display index for -R. (Use screencapture -D <id> when you want a full display by ID instead of a rectangle.)

screencoord emits coordinates in that same space. If something looks off on an external monitor, open an issue with your arrangement (primary size, relative positions, sample output).

Exit codes

Code Meaning
0 Success — coordinates printed and copied
1 Cancelled — no output, clipboard unchanged
2 Invalid arguments or overlay failure

Permissions

screencoord only draws a coordinate-selection overlay. It does not capture screenshots or read screen contents, so Screen Recording and Accessibility permissions are not required.

Requirements

  • macOS 13 or later

Download

Download the latest release on GitHub (universal macOS binary), or install with Homebrew:

brew tap ttscoff/thelab
brew install screencoord

The GitHub repository for this project is here, MIT licensed.

Related Projects