What it does

Decentralised-chat sink: upload each frame to a Matrix homeserver's media repository, then send an `m.text` summary followed by one `m.image` event per frame. Works with matrix.org, Element Cloud, or any self-hosted homeserver.

When to reach for it

Federated communities on Matrix that want video summaries in their rooms
Self-hosted Synapse / Dendrite — no webhook, just an access token
Bridged rooms where frames need to propagate to Telegram / IRC / Discord via Matrix

Install

npm i -g peepshow

Use it

MATRIX_HOMESERVER=https://matrix.org \
MATRIX_ACCESS_TOKEN=... \
MATRIX_ROOM_ID=!abc:matrix.org \
peepshow ./clip.mp4 --sink matrix

Make it automatic

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

Configuration

MATRIX_HOMESERVER Homeserver base URL (e.g. `https://matrix.org`). required
MATRIX_ACCESS_TOKEN Access token for the posting user. required
MATRIX_ROOM_ID Internal room id (`!abc:matrix.org`) or alias (`#room:matrix.org`). required
MATRIX_MAX_IMAGES Cap on frames uploaded. Default `20`.

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 Matrix 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 MATRIX_HOMESERVER="..."
export MATRIX_ACCESS_TOKEN="..."
export MATRIX_ROOM_ID="..."

2. Register as an auto-sink

peepshow sinks add matrix
peepshow sinks add matrix --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 Matrix 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'.

Matrix — Post every run to a Matrix room with frames as m.image events.