peepshow: Instructions file for Claude Code

AGENTS.md — peepshow

Generic agent context file. Consumed by Codex CLI, OpenAI Agents, Zed AI, and any tool that follows the AGENTS.md convention.

What peepshow is

CLI tool that turns videos and animated images (GIF/APNG/animated WebP) into a timeline of still frames + an extracted audio track + optional whisper.cpp / openai / groq / deepgram / assemblyai transcript, so an LLM can "watch" and "listen" to what's inside. Installed via npm i -g peepshow. Published at https://www.npmjs.com/package/peepshow.

When to invoke it

Trigger — user references a local file path, HTTP(s) URL, or data URI whose target is a video or animated image. Common extensions: mp4 mov mkv webm avi flv wmv ts mts m2ts 3gp ogv gif apng.

Don't fire for static images (png jpg jpeg static-webp) — LLMs already read those natively.

How to invoke

Preferred, most robust (structured JSON output; includes video metadata + tags):

peepshow "<path-or-url>" --emit json

Parse the stdout JSON:

• frames[] — ordered frame paths (chronological).
• video — container, codec, resolution, fps, duration, size, plus tags (title, director, producer, etc).
• extraction — strategy used (scene vs fps), ffmpeg source, elapsed ms. Plus framesDeduped + dedupDistance (perceptual-hash post-pass, 8×8 dHash, default-on), and motionSignalAvg + motionSignalLevel (low/medium/high) — average pairwise hamming across kept frames. Use the motion signal to colour narration; high motion + framesDeduped == 0 means every frame is genuinely distinct.

Read each frames[i].path as an image. Ground your answer in video.tags before describing frames.

Annotate the report after reading

Each run also writes report.html + manifest.json into outputDir. After you've understood the frames + transcript, pipe a JSON summary back so the report captures your synthesis for whoever opens it later:

echo '{"summary":"<2-4 sentences>","provider":"<your-tool-name>"}' \
  | peepshow report annotate "<outputDir>"