Screengrab

Quick macOS display snapshot. Captures what's currently on screen without opening a browser. Saves to /tmp or a custom path. Supports multiple displays and periodic watch mode. USE WHEN: Agent needs to see what's on the Mac's screen right now — for debugging visual state, checking what app is open, verifying output, or remote awareness without a full browser session. Also use to list connected displays or capture a specific one. DON'T USE WHEN: User wants to screenshot a specific URL or web page (use browser snapshot instead). Not for headless/offscreen rendering.

Thin wrapper around macOS screencapture. No dependencies beyond Python 3.

Requirements

• macOS only (/usr/sbin/screencapture)
• Script: scripts/screengrab.py

Commands

# Capture all displays → /tmp/screengrab-TIMESTAMP.png
python3 scripts/screengrab.py snap

# Custom output path
python3 scripts/screengrab.py snap --out ~/Desktop/snap.png

# Specific display (0=main, 1=second)
python3 scripts/screengrab.py snap --display 0

# Open in Preview immediately
python3 scripts/screengrab.py snap --open

# Quiet mode — just prints the file path (useful for piping to image tool)
python3 scripts/screengrab.py snap --quiet

# List connected displays
python3 scripts/screengrab.py list

# Periodic capture (every 30s)
python3 scripts/screengrab.py watch
python3 scripts/screengrab.py watch --interval 10 --out-dir ~/Desktop/snaps
python3 scripts/screengrab.py watch --count 5   # stop after N captures

Typical Agent Workflow

# Grab screen and analyze with image tool
path=$(python3 scripts/screengrab.py snap --quiet)
# Then pass $path to image analysis