What it does
Write both the structured archive (from the postgres sink) and frame embeddings into the same Postgres instance using the `pgvector` extension. One database for both metadata and RAG.
When to reach for it
- Single source of truth: SQL + vector search in the same `SELECT`
- Backup, replicate, and restore everything with one pg_dump
- Avoid running three services (sql + object store + vector DB) — one Postgres covers it
Install
npm i -g peepshow
npm i -g pgUse it
DATABASE_URL=postgres://... \
peepshow ./clip.mp4 --sink pgvectorMake it automatic
Register the sink once — every run fires it afterward. Scope by --when so it only runs for matching videos.
peepshow sinks add pgvector
peepshow sinks add pgvector --when extension=mp4,mov
peepshow sinks add pgvector --when path=/Volumes/Work/Configuration
DATABASE_URLPostgres connection string. The `vector` extension must be installed. requiredPEEPSHOW_PGVECTOR_DIMEmbedding dimension. Default 1536 (OpenAI).
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 pgvector 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 pgvector
peepshow sinks add pgvector --when extension=mp4,mov3. Example LLM session
You → drop a
.movinto Claude Code.Claude → auto-invokes
/peepshow:slides ./clip.mov. peepshow extracts frames + audio, thepgvectorsink forwards the run to the configured collection. Claude replies with a summary and a link to the created record.
The transcript text is a natural embedding target — index it next to the frames.
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'.