What it does
[Mastodon](https://joinmastodon.org) is the decentralised microblogging network at the heart of the Fediverse — same API, hundreds of independent instances. This sink posts one status per peepshow run via `POST https://<instance>/api/v1/statuses` with a form-encoded body (`status`, `visibility`, optional `spoiler_text`). Auth is a standard Bearer access token minted under Preferences → Development → New application. Status text is composed from the run title + frame count + duration, capped at the upstream default of 500 characters (instances can raise this; the sink uses the conservative default). Visibility defaults to `unlisted` so peepshow runs don't flood your followers' home timeline — opt up to `public` per-instance with `MASTODON_VISIBILITY=public`.
When to reach for it
- Post a public log of every video an agent processes for transparency / open-source community demos
- Quietly thread peepshow runs onto a private Mastodon account as a long-term durable audit trail (visibility=direct)
- Bridge peepshow into the wider Fediverse ecosystem (Pixelfed, Bookwyrm, GoToSocial) without per-platform integrations
Install
npm i -g peepshowUse it
MASTODON_INSTANCE="mastodon.social" \
MASTODON_ACCESS_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
peepshow ./clip.mp4 --sink mastodonMake it automatic
Register the sink once — every run fires it afterward. Scope by --when so it only runs for matching videos.
peepshow sinks add mastodon
peepshow sinks add mastodon --when extension=mp4,mov
peepshow sinks add mastodon --when path=/Volumes/Work/Configuration
MASTODON_INSTANCEInstance hostname (e.g. `mastodon.social`, `hachyderm.io`). Scheme + trailing slashes are stripped automatically. requiredMASTODON_ACCESS_TOKENOAuth2 access token (Bearer). Generate under Preferences → Development → New application. requiredMASTODON_VISIBILITYOne of `public|unlisted|private|direct`. Default `unlisted` — friendly to your followers.MASTODON_SPOILER_TEXTContent-warning text prepended to every status. Useful for `peepshow run` style tagging or NSFW guards.
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 Mastodon sink automatically when three things are true:
- the env vars below are exported in the agent's shell (or a project
.envit can load), - the
peepshowCLI is onPATH— install withnpm 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 MASTODON_INSTANCE="..."
export MASTODON_ACCESS_TOKEN="..."2. Register as an auto-sink
peepshow sinks add mastodon
peepshow sinks add mastodon --when extension=mp4,mov3. Example LLM session
You → drop a
.movinto Claude Code.Claude → auto-invokes
/peepshow:slides ./clip.mov. peepshow extracts frames + audio, theMastodonsink 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'.