What it does

Chart CLI usage, popular sinks, average run duration, and codec distribution in PostHog. Each peepshow run becomes a single event with rich properties (strategy, frame count, codec, duration, director, studio); flip `POSTHOG_PER_FRAME=1` for per-frame granularity.

When to reach for it

Product-analytics dashboards for an LLM pipeline that uses peepshow
Self-hosted PostHog: override `POSTHOG_HOST` to your instance
Funnel analysis: which codecs / resolutions cause the most frames per run

Install

npm i -g peepshow

Use it

POSTHOG_PROJECT_API_KEY=phc_... \
peepshow ./clip.mp4 --sink posthog

Make it automatic

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

Configuration

POSTHOG_PROJECT_API_KEY Project API key (`phc_…`). required
POSTHOG_HOST Override for EU / self-hosted. Default `https://us.posthog.com`.
POSTHOG_DISTINCT_ID `distinct_id` used on every event. Default `peepshow`.
POSTHOG_PER_FRAME `1` fires one additional `peepshow_frame` event per frame.

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 PostHog 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 POSTHOG_PROJECT_API_KEY="..."

2. Register as an auto-sink

peepshow sinks add posthog
peepshow sinks add posthog --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 PostHog sink forwards the run to the analytics stream as a tagged event. Claude replies with a summary and a link to the created record.

Transcript metadata (language, duration, silence ratio) tags each event.

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

PostHog — Capture every run as a PostHog product-analytics event.