Lensee

Lensee is a local video-skimming CLI built for agents.

It helps an agent read video more like a human reviewer: scan the whole file quickly, spot visually important moments, zoom into short ranges, and cut timestamped evidence clips. Instead of asking an agent to watch a video linearly, Lensee turns the video into contact sheets, frame maps, audio files, clips, and reels that agents can inspect and cite.

Video processing stays local. Lensee does not upload your media.

Install

Requirements:

• Node.js 20+
• ffmpeg and ffprobe on PATH

Install FFmpeg:

brew install ffmpeg

Run the CLI without a global install:

npx lensee --help

Or install it globally:

npm install -g lensee
lensee --help

Agent Skill

For Codex and other skill-aware agents, install the bundled lensee-video-skim skill. The skill teaches the agent when to survey broadly, when to inspect a tighter range, and how to report timestamped findings.

Standard skills installer:

npx skills add ryancen404/lensee --skill lensee-video-skim -a codex -y

Direct skill directory URL:

npx skills add https://github.com/ryancen404/lensee/tree/main/skills/lensee-video-skim -a codex -y

CLI fallback:

npx lensee skill --out ~/.codex/skills

Print the skill body:

npx lensee skill --print

Agent Workflow

Start with a broad survey:

lensee survey ./video.mp4 --out-dir ./out

Then inspect a candidate range:

lensee inspect ./video.mp4 --start 00:12:00 --end 00:13:30 --out-dir ./out

Cut evidence when a finding matters:

lensee clip ./video.mp4 --start 00:12:08 --end 00:12:20 --out ./clips/candidate.mp4

Commands print JSON so agents and scripts can consume output directly, except lensee skill --print, which prints the raw SKILL.md body.

Commands

| Command | Purpose | Example | | --- | --- | --- | | probe | Read video metadata with ffprobe. | lensee probe video.mp4 | | survey | Create broad paginated contact sheets for fast whole-video scanning. | lensee survey video.mp4 --preset normal --out-dir ./out | | inspect | Create denser sheets for a known time range. | lensee inspect video.mp4 --start 00:12:00 --end 00:13:30 --preset detail | | audio | Extract audio for transcription or separate audio analysis. | lensee audio video.mp4 --out ./audio.wav | | clip | Cut a short verification clip. | lensee clip video.mp4 --start 00:12:08 --end 00:12:20 --out ./candidate.mp4 | | reel | Assemble selected clips into one review reel. | lensee reel --clips clips.json --out ./selects.mp4 | | skill | Install or print the bundled agent skill. | lensee skill --out ~/.codex/skills |

Survey vs Inspect

Use survey to build the visual table of contents. Use inspect to zoom into short candidate ranges.

AI-friendly defaults:

• survey defaults to --layout grid --grid 6x6
• inspect defaults to --layout strip --grid 8x1
• inspect --layout grid defaults to --grid 4x4
• final partial pages shrink to the used row count

Presets control sampling interval:

| Command | Preset | Interval | | --- | --- | ---: | | survey | fast | 15s | | survey | normal | 8s | | survey | detail | 2s | | inspect | fast | 2s | | inspect | normal | 1s | | inspect | detail | 0.5s |

Explicit --interval overrides the selected preset. Explicit --grid overrides the layout default.

Output

By default, range-skimming commands write artifacts under:

lensee-output/<video-id>/

Use --out-dir to choose the artifact root:

lensee survey video.mp4 --out-dir ./out
lensee inspect video.mp4 --start 00:12:00 --end 00:13:30 --out-dir ./out

survey and inspect create:

out/
  <video-id>/
    frames/
    sheets/
    *_frame_map.json

clip and reel use explicit --out paths.

Development

npm install
npm run dev -- --help
npm test
npm run typecheck
npm run build
npm run check