What it does

Route peepshow runs straight into a Messages.app conversation on macOS. The sink builds an AppleScript `tell application "Messages"` block and pipes it into `osascript -`: one text bubble with title + duration + frame count + a transcript snippet (when available), then each frame as a separate image attachment. No API keys — it uses whatever iMessage / SMS account Messages.app is already signed into. Skips silently on non-darwin unless `IMESSAGE_ALLOW_NON_DARWIN=1` is set.

When to reach for it

Ping a teammate on their phone the moment a bug clip gets extracted
Share a quick clip with a non-technical stakeholder who lives in Messages
Local-only delivery that never touches a third-party webhook or bot platform

Install

npm i -g peepshow

Use it

IMESSAGE_BUDDY=+15551234567 \
peepshow ./bug.mov --sink imessage

Make it automatic

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

Configuration

IMESSAGE_BUDDY Phone number (e.g. `+15551234567`) or email address of the recipient. required
PEEPSHOW_IMESSAGE_BUDDY Alias for `IMESSAGE_BUDDY`; wins when both are set.
IMESSAGE_SERVICE `iMessage` (default) · `SMS` (requires iPhone SMS forwarding).
IMESSAGE_MAX_FRAMES Cap on frame attachments. Default `4`.
IMESSAGE_ALLOW_NON_DARWIN `1` / `true` / `yes` to attempt on non-macOS (CI dry-runs).

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 iMessage 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 IMESSAGE_BUDDY="..."

2. Register as an auto-sink

peepshow sinks add imessage
peepshow sinks add imessage --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 iMessage sink forwards the run to the configured channel. Claude replies with a summary and a link to the created record.

The transcript snippet is posted alongside the frames as a secondary message.

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'.

iMessage — DM a peepshow run to a buddy via Messages.app on macOS.