What it does
Upload every extracted frame to an S3-compatible bucket under a deterministic `runs/{id}/frame_NNNN.jpg` prefix. Plays nicely with any gateway that implements the AWS SigV4 S3 API, including self-hosted MinIO.
When to reach for it
- Durable cold storage for long-running agent sessions
- Share frames across a team by bucket ACL instead of file transfer
- Feed a CDN or a vector-embedding pipeline downstream
Install
npm i -g peepshow
npm i -g @aws-sdk/client-s3Use it
peepshow ./clip.mov --sink s3 \
--sink-arg bucket=my-peepshow \
--sink-arg endpoint=https://nyc3.digitaloceanspaces.comMake it automatic
Register the sink once — every run fires it afterward. Scope by --when so it only runs for matching videos.
peepshow sinks add s3
peepshow sinks add s3 --when extension=mp4,mov
peepshow sinks add s3 --when path=/Volumes/Work/Configuration
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEYCredentials for the bucket. requiredAWS_REGIONRegion, required for AWS; arbitrary for most S3-compatible services. requiredPEEPSHOW_S3_BUCKETBucket name (alternative to `--sink-arg bucket`).PEEPSHOW_S3_ENDPOINTNon-AWS endpoint URL for R2, MinIO, DO Spaces, etc.
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 S3-compatible storage 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 AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="..."2. Register as an auto-sink
peepshow sinks add s3
peepshow sinks add s3 --when extension=mp4,mov3. Example LLM session
You → drop a
.movinto Claude Code.Claude → auto-invokes
/peepshow:slides ./clip.mov. peepshow extracts frames + audio, theS3-compatible storagesink forwards the run to the configured bucket / folder. Claude replies with a summary and a link to the created record.
The full transcript JSON is saved next to the frames in the manifest.
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'.