Local macOS screenshots for coding agents.
Take a screenshot. screenshotter optimizes it locally and copies it to your clipboard.
Install
git clone https://github.com/mgranados/screenshotter.git
cd screenshotter
node bin/screenshotter.mjs doctorOptional:
mkdir -p ~/.local/bin ln -sf "$PWD/bin/screenshotter.mjs" ~/.local/bin/screenshotter
Use
screenshotter watch --verbose
Take a screenshot with Cmd+Shift+3 or Cmd+Shift+4, then paste into Codex, Claude, or another agent with Cmd+V.
For pi:
Then run /screenshotter on.
Savings
| Size | Original | Default | Size saved | Bandwidth saved / 1k |
|---|---|---|---|---|
| Pro Display XDR 6016x3384 | 5.48 MB | 0.89 MB | 93% | 5.0 GB |
| 16in MacBook Pro 3456x2234 | 1.86 MB | 0.83 MB | 89% | 1.6 GB |
| 14in MacBook Pro 3024x1964 | 2.34 MB | 0.75 MB | 91% | 2.1 GB |
| Window 1920x1200 | 1.04 MB | 0.40 MB | 81% | 0.8 GB |
| Window 1440x900 | 0.63 MB | 0.38 MB | 68% | 0.4 GB |
Average from 5 recent screenshots. Default preserves readability. Token mode resizes for lower API image-token cost. Downscale defaults are checked with Apple Vision text-readability benchmarks.
Default mode helps with:
- Upload bandwidth: often
2-5 MB -> <1 MB. - Paste/send latency: less image data for Codex or Claude to ingest.
- Local storage: optimized copies are smaller.
- Reliability: less likely to hit attachment limits.
- Readability per byte: efficient encoding while keeping dimensions high.
Profiles
screenshotter watch --profile readability # default
screenshotter watch --profile balanced
screenshotter watch --profile tokenIn pi: /screenshotter readability, /screenshotter balanced, or /screenshotter token.
Commands
screenshotter watch --verbose screenshotter clip --target codex-app screenshotter claude-app --verbose screenshotter prepare-latest --target manual --json screenshotter claim --target manual --json screenshotter bench --latest 20 --tokens --json screenshotter doctor
MCP, experimental:
codex mcp add screenshotter -- screenshotter mcp-server claude mcp add screenshotter -- screenshotter mcp-server
No symlink:
node bin/screenshotter.mjs watch --verbose
Verbose runs write JSONL logs to:
~/Library/Application Support/screenshotter/logs/events.jsonl
License
MIT.