Turn a video — or an animated GIF, APNG, or WebP — into a timeline of still frames so any LLM canwatchit.
Ships as aClaude Code pluginwith drag-and-drop auto-invoke, native manifests forCursor · Windsurf · Cline · Codex CLI · Gemini CLI, and a standalone CLI with19 pluggable sinks(SQLite, Postgres, S3-compatible, Slack, Discord, Webhook, GraphQL, Notion, Obsidian, IDE attachments, Linear, GitHub Issues, Sentry, Chroma, Qdrant, Pinecone, pgvector, MongoDB, MemPalace).
Who it's for
Whatever's in your video — a bug, a break-in, a lecture, an exploit — peepshow turns it into still frames an LLM already knows how to reason about.
A QA engineer screen-records a flicker. A designer sends a 12-second Loom. A user uploads a.movwith the frame that breaks everything. peepshow turns that clip into scene-aware stills so the model sees the bug frame-by-frame.
# drop a repro into Claude — the hook does the rest
peepshow ./bug-repro.mov --strategy scene --max 12An hour of overnight camera footage is hours of nothing followed by twelve seconds that matter. peepshow's scene detector flags the motion, the LLM narrates what changed between frames, and you get a readable incident timeline — not a scrub bar.
# 1 hour of CCTV → a timeline of motion events
peepshow ./cctv-2026-04-23.mp4 --strategy scene --threshold 0.18 --max 60 \
--sink sqlite:./incidents.db --tag camera=front-doorLecture captures, fieldwork timelapses, documentary clips, microscopy. The LLM can read a slide, a phase change, a titration colour shift — it just needs a well-chosen frame. peepshow picks frames that change; you get notes the LLM can actually reason about.
# 50-minute lecture -> one still per slide change
peepshow ./lecture-04.mp4 --strategy scene --threshold 0.25 \
--emit markdown --sink obsidian:~/vault/LecturesCVE repro videos, exploit PoCs, red-team recordings — evidence is only useful if reviewable. peepshow extracts the exact frames where state changes so an analyst, a report, or an LLM can cite them directly. No re-watching at 1x.
# PoC screencast -> pinned evidence + frame-accurate captions
peepshow ./cve-2026-1138-repro.mp4 --strategy scene --max 20 \
--emit xml --sink github-issues:owner/repo --tag severity=highVideo content is a wall to users on screen readers. peepshow converts the visual track into per-scene stills so an LLM can describe each moment — alt text that reflects the whole story, not a single thumbnail.
# feed a screen reader / captioning pipeline
peepshow ./training-video.mp4 --strategy scene --emit json \
--sink webhook:https://a11y.example/describeone slideshow · any LLM · any video
Drop an.mp4,.mov, or.gifinto the Claude prompt. AUserPromptSubmithook detects the path and auto-invokes/peepshow:slides. No slash command required.
Defaults to ffmpeg'sselect='gt(scene,0.3)'filter — catches visually distinct moments, not fixed-fps noise. Falls back to interval sampling for short clips.
Every run can fan out to databases, object stores, vector DBs, issue trackers, chat, and wiki systems. All tested, all shipped on npm.Full list →
Sinks fire only when the input matches —--when director=Kubrick,--when path=/Volumes/Work/,--when extension=mp4,mov. Turns peepshow into a smart router.
VideoToolbox on macOS, VAAPI on Linux, D3D11VA on Windows — auto-detected. Prefers native ffmpeg over the bundled static build for extra speed.
[PEEPSHOW:decoding:42%]mid-run,[PEEPSHOW:5frm:scene:system]after,[PEEPSHOW|3s]with three auto-sinks armed.
Ships native agent manifests forClaude · Cursor · Windsurf · Cline · Codex · Gemini. Integration snippets foraider · llm · Copilot · Continue · Cody · Zedin the docs.
Title, director, producer, show, genre, creation time — every tag inside the video's container flows into the JSON the LLM sees. Ground answers in what the videosays it is, not just what's on screen.
A one-line live indicator rendered in the Claude Code statusline — shows whether peepshow is idle, probing ffmpeg, decoding, or done. Also reports which sinks fired, how many frames were extracted, which strategy won.
Rich states out of the box:[PEEPSHOW:decoding:42%]mid-run,[PEEPSHOW:6frm:scene:system|3s]after (six frames, scene-detection won, used native ffmpeg, three auto-sinks armed),[PEEPSHOW:sink:slack:posted]when a sink succeeds. All readable at a glance without leaving the editor.
peepshow sinks add obsidianonce — every future run fires it. Config at~/.peepshow/sinks.json. The statusline shows how many are armed:[PEEPSHOW|3s].
--when--when director=Kubrick,--when extension=mp4,mov,--when path=/Volumes/Work/. Sinks only fire when the input matches. ANDed within a sink, ORed across values.
Title, director, producer, show, genre, creation time — every tag inside the video's container reaches both the LLMandeach sink's payload.--when key=valuecan match any of them.
--emit paths(default),--emit json(structured),--emit markdown(human-readable),--emit caveman(token-compressed viacaveman). Pair with any agent pipeline.
PEEPSHOW_FFMPEGenv → nativeffmpegon PATH → bundledffmpeg-static. System build wins because brew/choco/apt ship with VideoToolbox, NVENC, QSV, VAAPI, D3D11VA. Static build is the zero-config safety net.
A sink is any executable that reads the--emit jsonpayload on stdin. Shell, Node, Python, Go, Rust — doesn't matter. Register persistent ones withpeepshow sinks add-cmd 'your-cmd'.
Installcavemanon PATH — peepshow picks it up and auto-compresses output unless you've explicitly set--emit. Opt out withPEEPSHOW_AUTO_COMPRESS=0.
Same pipeline, different container. Meme-length loops and multi-frame screenshots all flow through the same scene-detect → prune → sink pipeline.
Two steps. Runtime from npm, plugin from GitHub.
npm i -g peepshow # adds peepshow + all peepshow-sink-* bins to PATH
npx peepshow ./video.mp4 # one-shot, no installOptional native ffmpeg for faster hardware decoding:
brew install ffmpeg # macOS
choco install ffmpeg-full # Windows
sudo apt install ffmpeg # Debian / UbuntuSkip entirely — peepshow bundlesffmpeg-staticas a fallback.
claude plugin marketplace add t0mtaylor/peepshow
claude plugin install peepshow@peepshow-marketplaceRestartclaude— the/peepshow:slidesskill is live, and the drag-and-drop hook fires on every prompt.
peepshow ./bug.mov # paths + human-readable stats
peepshow ./demo.mp4 --emit json | jq # structured
peepshow ./loop.gif --emit caveman # token-compressed
peepshow ./keynote.mp4 --sink folder:/shared # fan outEvery extract can fan out to any number of destinations. A sink reads the JSON payload on stdin, does anything. Conditional matchers (--when) mean each sink only fires when the input fits.
Browse the full sink catalogue →
peepshow sinks add folder:/Volumes/Shared/peepshow
peepshow sinks add postgres
peepshow sinks add-cmd 'node ~/scripts/obsidian-sync.js'
peepshow sinks list # see what's active
peepshow ./any-video.mp4 # all three fire
peepshow ./one-off.mp4 --no-auto-sinks # skip for this run--whenpeepshow sinks add folder:/Volumes/Family --when extension=mp4,mov
peepshow sinks add postgres --when path=/Volumes/Work/
peepshow sinks add folder:/Cinema/Kubrick --when director=Kubrick --when genre=Thriller
peepshow sinks add-cmd 'node x.js' --when filename='*vacation*'Native manifests for every major LLM CLI. Install peepshow once; every agent picks it up.
| Agent | Manifest | Install |
|---|---|---|
| Claude Code | .claude-plugin/+skills/+hooks/ | claude plugin marketplace add t0mtaylor/peepshow |
| Cursor | .cursor/rules/peepshow.mdc | picked up when peepshow is installed into the project |
| Windsurf | .windsurf/rules/peepshow.md | same |
| Cline | .clinerules/peepshow.md | same |
| Codex CLI | .codex/hooks.json+.codex/config.toml | SessionStart hook announces peepshow; invoke via Bash |
| Gemini CLI | gemini-extension.json+GEMINI.md | point Gemini at the repo as a custom command |
| Codex agents / Zed AI | AGENTS.md | convention-based pickup |
| Generic agents registry | .agents/plugins/marketplace.json | npx skills add t0mtaylor/peepshow(once supported) |
Deep-dive each agent integration →
Plus documented integration snippets forCopilot CLI · aider · llm · Continue · Cody · Zed AI · Perplexity · Ollamaindocs/INTEGRATIONS.md.
npm i peepshowpulls inffmpeg-staticas a fallback. Native ffmpeg (via brew / choco / apt) is preferred for hardware decoding but optional.UserPromptSubmithook spots the video path, injects a reminder into Claude's context, and Claude auto-invokes/peepshow:slides <path>. Frames are extracted, read as images, and Claude answers — without you typing the slash command.--emit jsonpayload on stdin is a valid sink — bash, Node, Python, Go, Rust, whatever. Register persistent ones viapeepshow sinks add-cmd 'your command'. Seethe sink spec.peepshow ... --emit cavemanprints an ultra-terse one-line summary + paths, designed for token-compressed LLM setups likeJuliusBrussee/caveman. Saves ~70% of peepshow's preamble tokens.