What it does

Bear is a beloved markdown notes app on Apple platforms with iCloud sync, hashtag-style tagging, and a deep `bear://` x-callback-url scheme. This sink turns every peepshow run into a markdown note: the body is rendered as `## Metadata` / `## Tags` / `## Frames` / `## Transcript` sections, the title is derived from `video.tags.title` / `video.tags.show` or a frame-count fallback, and frame paths render as clickable `[basename](file:///abs/path)` links. `BEAR_MODE=append` switches to `/add-text` for an existing note via `BEAR_NOTE_ID`. Bodies that exceed Bear's ~32 KB URL ceiling are truncated on a newline boundary with a footer pointing back at the on-disk frames directory. Skips silently on non-darwin unless `BEAR_ALLOW_NON_DARWIN=1` is set.

When to reach for it

Personal research notes synced across iPhone / iPad / Mac via iCloud — every peepshow run lands in your existing Bear graph
Markdown-first workflow where Apple Notes' HTML rendering doesn't fit and Obsidian / Logseq feel heavy
Bear's hashtag tagging — surface every clip under `#peepshow` plus per-run `BEAR_TAGS` like `#research` or `#kubrick`

Install

npm i -g peepshow

Use it

BEAR_TAGS=research,kubrick \
peepshow ./lecture.mp4 --sink bear

Make it automatic

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

Configuration

BEAR_TITLE Override the derived title.
BEAR_TAGS Comma-separated tag names (no `#` needed; sink prefixes). `#peepshow` is always added.
BEAR_OPEN_NOTE `yes` to surface the note after writing it. Default `no`.
BEAR_TOKEN Bear → settings → advanced API token. Not required for `create` / `add-text`; forwarded when set.
BEAR_MODE `create` (new note, default) or `append` (add to existing note via `/add-text`).
BEAR_NOTE_ID Existing note's unique identifier. Required when `BEAR_MODE=append`.
BEAR_ALLOW_NON_DARWIN `1` to force-run on non-darwin platforms (CI / debug).

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 Bear 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

This sink has no required env vars — it writes to a local path. Pass the destination via --sink-arg:

BEAR_TAGS=research,kubrick \
peepshow ./lecture.mp4 --sink bear

2. Register as an auto-sink

peepshow sinks add bear
peepshow sinks add bear --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 Bear sink forwards the run to a new page in your knowledge base. Claude replies with a summary and a link to the created record.

The transcript text is embedded alongside the frame gallery on the created page.

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

Bear — File every peepshow run as a markdown note in Bear on macOS / iOS.