What it does
For teams: archive every peepshow run into shared Postgres. Auto-creates the tables on first write, uses transactions for atomicity, supports standard `DATABASE_URL` or split credentials.
When to reach for it
- Centralise every video an agent has processed across your team
- Join peepshow metadata with app tables — link a run to a user, a ticket, a release
- Pair with the pgvector sink on the same database for a single-source video+vectors store
Install
npm i -g peepshow
npm i -g pgUse it
DATABASE_URL=postgres://user:pass@host:5432/db \
peepshow ./demo.mp4 --sink postgresMake it automatic
Register the sink once — every run fires it afterward. Scope by --when so it only runs for matching videos.
peepshow sinks add postgres
peepshow sinks add postgres --when extension=mp4,mov
peepshow sinks add postgres --when path=/Volumes/Work/Configuration
DATABASE_URLFull connection string. Preferred. requiredPGHOST / PGUSER / PGPASSWORD / PGDATABASE / PGPORTSplit credentials if no DATABASE_URL.PEEPSHOW_POSTGRES_SCHEMASchema name. Default `peepshow`.
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 Postgres 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 DATABASE_URL="..."2. Register as an auto-sink
peepshow sinks add postgres
peepshow sinks add postgres --when extension=mp4,mov3. Example LLM session
You → drop a
.movinto Claude Code.Claude → auto-invokes
/peepshow:slides ./clip.mov. peepshow extracts frames + audio, thePostgressink forwards the run to the configured database. 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'.