What it does

Raycast is macOS's scriptable launcher. This sink turns every peepshow run into a discoverable artefact there: a `peepshow-<stamp>.json` manifest lands next to a sibling folder of copied frames, and a companion Raycast script command (written once, idempotently) opens the most recent run in Finder with one keystroke. Skips silently on non-darwin unless `RAYCAST_SCRIPT_DIR` is set.

When to reach for it

Macs where Raycast is the launcher and you want the latest clip one hotkey away
Triage workflow: drop a bug video, pop open Raycast, jump straight to the frames + manifest
Share a peepshow history via a synced Script Commands folder across machines

Install

npm i -g peepshow

Use it

peepshow ./demo.mp4 --sink raycast
# first run also drops ~/Library/Application Support/Raycast/script-commands/peepshow/peepshow-show-last.sh

Make it automatic

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

Configuration

RAYCAST_SCRIPT_DIR Override the target dir. Also unlocks the sink on non-darwin platforms. Default `~/Library/Application Support/Raycast/script-commands/peepshow/`.
PEEPSHOW_RAYCAST_DIR Alias for `RAYCAST_SCRIPT_DIR`; wins when both are set.
RAYCAST_MODE `manifest` (default) · `quicklook` (reserved — falls back to manifest with a stderr note for now).

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 Raycast 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

This sink has no required env vars — it writes to a local path. Pass the destination via --sink-arg:

peepshow ./demo.mp4 --sink raycast
# first run also drops ~/Library/Application Support/Raycast/script-commands/peepshow/peepshow-show-last.sh

2. Register as an auto-sink

peepshow sinks add raycast
peepshow sinks add raycast --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 Raycast sink forwards the run to the configured Raycast 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'.

Raycast — Expose every peepshow run as a Raycast script command on macOS.