screenshotter

Local-first macOS screenshots for coding agents. screenshotter compresses screenshots, captures useful screen context, and puts both on the clipboard ready to paste into Codex, Claude, or another agent.

No telemetry. Screenshot processing, text extraction, and storage all happen locally on your Mac.

Install

Requires macOS and Node.js 20+.

npm install -g @marttinn/screenshotter
screenshotter doctor --prompt-permissions

Recommended setup

This is the workflow shown in the demo:

screenshotter toolbar --clipboard-mode attachments

Then:

1. Take a screenshot using your usual macOS action or shortcut.
2. Wait for the menu-bar icon to confirm it is ready.
3. Paste with Cmd+V.

screenshotter reacts to Apple’s screenshot file marker, with the documented Screenshot … filename as a fallback—not to a particular keyboard shortcut. Default shortcuts, remapped shortcuts, and Screenshot.app all work when they save to your configured macOS screenshot folder.

The clipboard contains two attachments:

• a locally compressed image;
• a small Markdown file with the frontmost app, window, and visible text from macOS Accessibility.

OCR is off unless you explicitly enable it.

Prefer screenshots on the clipboard?

If your screenshot action copies an image instead of saving a file, screenshotter clipboard can process it. With the default macOS shortcuts, holding Control selects this behavior:

• Ctrl+Shift+Cmd+3 copies the full screen;
• Ctrl+Shift+Cmd+4 copies a selected area.

To optimize the image currently on the clipboard and put the smaller version back:

screenshotter clipboard

If your usual screenshot action writes to the clipboard, add --clipboard-input to the recommended toolbar command and leave it running:

screenshotter toolbar --clipboard-input --clipboard-mode attachments

Now any screenshot action that puts an image-only item on the clipboard can trigger processing; the keyboard combination itself is irrelevant. File copies and rich clipboard content such as URLs, HTML, RTF, or text are ignored. Wait for the menu-bar confirmation, then paste the optimized attachments with Cmd+V.

Useful variations

# Image only
screenshotter toolbar

# Same attachment workflow without the menu-bar UI
screenshotter watch --clipboard-mode attachments

# Smaller output
screenshotter toolbar --profile balanced
screenshotter toolbar --profile token

# Accessibility text, then OCR only when direct text is unavailable
screenshotter toolbar --text-provider auto --clipboard-mode attachments

# Process the newest saved screenshot once
screenshotter clip --clipboard-mode attachments

Options

Most options work with toolbar, watch, clip, clipboard, and prepare.

Option	What it does
--profile readability	Default; prioritizes readable text and UI detail.
--profile balanced	Medium-size output.
--profile token	Smallest built-in profile.
--with-text	Captures visible text through macOS Accessibility.
--with-target-context	Records the frontmost app and window under the pointer.
--text-provider accessibility	Direct text only; this is the default with --with-text.
--text-provider auto	Accessibility first, then Apple Vision OCR fallback.
--ocr	Forces Apple Vision OCR.
--no-ocr	Prevents OCR fallback.
--clipboard-mode image	Copies only image data; the default.
--clipboard-mode attachments	Captures direct text and app/window context, then copies the image and context Markdown file; recommended.
--clipboard-mode both	Copies text and image data as separate pasteboard items.
--clipboard-mode files	Copies local file references.
--clipboard-mode markdown	Copies a text prompt containing local paths and context.
--clipboard-mode text	Copies extracted text only.
--clipboard-mode codex-inline	Activates Codex and pastes text followed by the image.
--clipboard-input	Watches for screenshot-like image-only clipboard changes; ignores files and rich content.
--clipboard-poll-ms <ms>	Tunes the native metadata-only change monitor; the default is 500 ms. Clipboard image data is read only after a change.
--no-clipboard	Prepares screenshots without changing the clipboard.
--target <name>	Labels prepared screenshots for a specific consumer.
--poll-ms <ms>	Changes the fallback watcher and clipboard polling interval.
--verbose	Prints timings and delivery details.
--json	Returns machine-readable output for one-shot commands.
--dry-run	Shows the planned result without clipboard delivery.

Fine-grained image controls are available when needed: --optimizer, --max-long-edge, --long-edge-percent, --min-long-edge, --jpeg-quality, --max-output-bytes, and --max-patches. Run screenshotter help for the complete command reference.

Other integrations

Install the pi package and enable live capture:

pi install npm:@marttinn/screenshotter

Then run /screenshotter on in pi.

Experimental MCP server:

codex mcp add screenshotter -- screenshotter mcp-server
claude mcp add screenshotter -- screenshotter mcp-server

See Codex usage, Claude usage, and agent integration for adapter-specific workflows.

Data and maintenance

Prepared images, context files, statistics, and optional logs live under:

~/Library/Application Support/screenshotter

screenshotter status --json
screenshotter stats --json
screenshotter gc --json

Ready records expire after 24 hours, claimed or cleared records after 30 days, and the store is bounded to 500 records by default.

Development

git clone https://github.com/mgranados/screenshotter.git
cd screenshotter
npm install
npm run check
node bin/screenshotter.mjs doctor

When running from source, replace screenshotter with node bin/screenshotter.mjs.

License

MIT.