What it does

Push peepshow runs into a Telegram chat as a summary message plus one or more photo albums. Longer runs chunk automatically into 10-photo `sendMediaGroup` calls. Works with any bot token from BotFather and supports local Bot API servers via `TELEGRAM_API_URL`.

When to reach for it

Personal bot that summarises dropped videos into a private Telegram channel
Group chat where teammates share reference clips and want frames inline
Local Bot API server / on-prem deployment via `TELEGRAM_API_URL`

Install

npm i -g peepshow

Use it

TELEGRAM_BOT_TOKEN=123:abc \
TELEGRAM_CHAT_ID=-1001234567890 \
peepshow ./clip.mp4 --sink telegram

Make it automatic

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

Configuration

TELEGRAM_BOT_TOKEN Bot token from @BotFather. required
TELEGRAM_CHAT_ID `-100…` group id, `@username`, or numeric user id. required
TELEGRAM_API_URL Override for local Bot API servers. Default `https://api.telegram.org`.
TELEGRAM_PARSE_MODE `MarkdownV2` | `HTML`. Default `MarkdownV2`.

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 Telegram 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 TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."

2. Register as an auto-sink

peepshow sinks add telegram
peepshow sinks add telegram --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 Telegram 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'.

Telegram — Post every run to a Telegram chat with frames as an album.