What it does

Create a per-run subfolder under a Box parent and upload every frame plus a `manifest.json`. Uses Box's simple-upload endpoint (tiny files like JPEG frames don't need chunked `upload_sessions`). Handles folder-name collisions by reusing the existing folder id.

When to reach for it

Enterprise Box as the canonical store — JWT app + long-lived tokens
Regulated industries requiring Box's compliance posture
Re-run idempotency: collision on `BOX_RUN_FOLDER_NAME` lands files in the same folder

Install

npm i -g peepshow

Use it

BOX_ACCESS_TOKEN=... \
BOX_PARENT_FOLDER_ID=123456789 \
peepshow ./clip.mp4 --sink box

Make it automatic

peepshow sinks add box
peepshow sinks add box --when extension=mp4,mov
peepshow sinks add box --when path=/Volumes/Work/

Configuration

BOX_ACCESS_TOKEN OAuth 2, JWT app, or developer bearer token. required
BOX_PARENT_FOLDER_ID Numeric folder id. `"0"` is the authenticated user's root folder. required
BOX_API_URL Override for Box for Government / private hosts.
BOX_UPLOAD_URL Override for the upload host.
BOX_RUN_FOLDER_NAME Pin the subfolder name instead of deriving a timestamp.

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 Box sink automatically when three things are true:

the env vars below are exported in the agent's shell (or a project .env it can load),
the peepshow CLI is on PATH — install with npm 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 BOX_ACCESS_TOKEN="..."
export BOX_PARENT_FOLDER_ID="..."

2. Register as an auto-sink

peepshow sinks add box
peepshow sinks add box --when extension=mp4,mov

3. Example LLM session

You → drop a .mov into Claude Code.
Claude → auto-invokes /peepshow:slides ./clip.mov. peepshow extracts frames + audio, the Box sink 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'.

Box — Upload frames and manifest to a Box folder.