What it does

macOS Shortcuts lets anyone wire up hundreds of system actions — post to Messages, describe an image with Apple Intelligence, save to Photos, run an AppleScript, hit a REST API — without writing code. This sink turns every peepshow run into a trigger for any Shortcut you've built. Two modes: `payload` writes the full `--emit json` payload to a temp file and calls `shortcuts run <NAME> --input-path <tempfile>` once; `frames` calls the Shortcut once per extracted frame, passing the image path directly. Skips silently on non-darwin unless `SHORTCUT_ALLOW_NON_DARWIN=1` is set.

When to reach for it

You've built a personal automation in Shortcuts.app and want every peepshow clip to trigger it
Route frames through Apple Intelligence (`Use Model` action) without an API key
Bridge peepshow into iOS apps via iCloud-synced Shortcuts — share sheets, Focus filters, Home Screen widgets

Install

npm i -g peepshow

Use it

SHORTCUT_NAME="Summarise peepshow clip" \
peepshow ./demo.mp4 --sink shortcuts

Make it automatic

peepshow sinks add shortcuts
peepshow sinks add shortcuts --when extension=mp4,mov
peepshow sinks add shortcuts --when path=/Volumes/Work/

Configuration

SHORTCUT_NAME Exact name of the Shortcut as shown in Shortcuts.app. required
PEEPSHOW_SHORTCUT_NAME Alias for `SHORTCUT_NAME`; wins when both are set.
SHORTCUT_MODE `payload` (default — full JSON on disk) or `frames` (one invocation per extracted frame, image as input).
SHORTCUT_OUTPUT_PATH Forwarded to `shortcuts run` as `--output-path`. Most Shortcuts don't need one.
SHORTCUT_ALLOW_NON_DARWIN `1` to force-run on non-darwin platforms (CI / debug).

Use with an LLM agent

Every peepshow sink reads its config from env vars and receives a single JSON payload on stdin. An LLM agent (Claude Code, Cursor, Windsurf, Gemini, Codex) can drive the macOS Shortcuts sink automatically when three things are true:

the env vars below are exported in the agent's shell (or a project .env it can load),
the peepshow CLI is on PATH — install with npm i -g peepshow,
a peepshow auto-sink is registered for the run (optional but recommended — makes invocation zero-argument).

1. Set the environment

# Add to ~/.zshrc, ~/.bashrc, or a project .env the agent can load
export SHORTCUT_NAME="..."

2. Register as an auto-sink

peepshow sinks add shortcuts
peepshow sinks add shortcuts --when extension=mp4,mov

3. Example LLM session

You → drop a .mov into Claude Code.
Claude → auto-invokes /peepshow:slides ./clip.mov. peepshow extracts frames + audio, the macOS Shortcuts sink forwards the run to the configured macOS Shortcuts target. Claude replies with a summary and a link to the created record.

The transcript rides along in the payload whenever the audio pass transcribes successfully.

Write your own

A sink is any executable that reads the --emit json payload on stdin. Shell, Node, Python, Go — the spec's in docs/PLUGINS.md. Register persistent ones with peepshow sinks add-cmd 'your-command'.

macOS Shortcuts — Fire a user-created Shortcut in Shortcuts.app with every peepshow run.