What it does

Create a Shortcut (formerly Clubhouse) story with a markdown description of the run, upload each frame via `/files`, and link the resulting file ids back onto the story. Supports creating new stories or attaching files to an existing `SHORTCUT_STORY_PUBLIC_ID`.

When to reach for it

Engineering teams on Shortcut who want video evidence on every bug story
Feature discovery: open a `feature` story with reference-clip frames attached
Hosted Shortcut mock / staging: override `SHORTCUT_API_URL` for integration tests

Install

npm i -g peepshow

Use it

SHORTCUT_TOKEN=... \
SHORTCUT_PROJECT_ID=1234 \
SHORTCUT_STORY_TYPE=bug \
peepshow ./bug-repro.mov --sink shortcut

Make it automatic

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

Configuration

SHORTCUT_TOKEN API token, sent as `Shortcut-Token` header. required
SHORTCUT_PROJECT_ID Numeric project id. Required unless `SHORTCUT_STORY_PUBLIC_ID` is set.
SHORTCUT_STORY_PUBLIC_ID Attach to an existing story; skip the create step.
SHORTCUT_STORY_TYPE `feature` | `chore` | `bug`. Default `bug`.
SHORTCUT_API_URL Override for self-hosted / staging. Default `https://api.app.shortcut.com/api/v3`.

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 Shortcut 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 SHORTCUT_TOKEN="..."

2. Register as an auto-sink

peepshow sinks add shortcut
peepshow sinks add shortcut --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 Shortcut sink forwards the run to a new issue with the frames attached. Claude replies with a summary and a link to the created record.

Transcript appears in the issue body, giving triage a copy-paste-able record of what was said.

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

Shortcut — Open a Shortcut story with every frame linked as a file.