What it does

Leave a file-level comment on a Figma design summarising the peepshow run — metadata (title, codec, duration, resolution, director, studio) plus a bulleted frame list. When `FIGMA_IMAGE_BASE` is set, each frame name becomes a markdown link to the hosted image.

When to reach for it

Design reviews where video references belong on the same Figma file as the mocks
Async UX research: video findings commented against the prototype file
CDN-hosted frames: frame names become clickable thumbnails inside Figma

Install

npm i -g peepshow

Use it

FIGMA_TOKEN=figd_... \
FIGMA_FILE_KEY=abc123XYZ \
peepshow ./prototype-demo.mp4 --sink figma

Make it automatic

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

Configuration

FIGMA_TOKEN Personal access token (sent as `X-Figma-Token`). required
FIGMA_FILE_KEY File key from the Figma URL (`/file/<KEY>/...`). required
FIGMA_IMAGE_BASE URL prefix for hosted frames; turns each frame line into a markdown link.
FIGMA_MAX_FRAMES_PER_COMMENT Cap on frame lines per comment. Default `20`.
FIGMA_API_URL Override for self-hosted proxies. Default `https://api.figma.com/v1`.

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 Figma 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 FIGMA_TOKEN="..."
export FIGMA_FILE_KEY="..."

2. Register as an auto-sink

peepshow sinks add figma
peepshow sinks add figma --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 Figma sink forwards the run to the configured board. Claude replies with a summary and a link to the created record.

The transcript rides along in the payload whenever the audio pass transcribes successfully.

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'.

Figma — Comment every run onto a Figma file.