video-to-skill

eyeroll

AI eyes that roll through video footage — watch, understand, act.

eyeroll is a Claude Code plugin that analyzes screen recordings, Loom videos, YouTube links, and screenshots, then helps coding agents fix bugs, build features, and create skills.

Install

# Add the plugin to Claude Code
/plugin marketplace add mnvsk97/eyeroll
/plugin install eyeroll@mnvsk97-eyeroll

# Install the CLI
pip install eyeroll[gemini]      # Gemini Flash API (recommended)
pip install eyeroll[twelvelabs]  # TwelveLabs direct video understanding
pip install eyeroll[openai]      # OpenAI GPT-4o + OpenRouter/Groq/Grok/Cerebras
pip install eyeroll              # Ollama only (local, no API key) — requires Pillow
pip install eyeroll[all]         # everything

Setup

/eyeroll:init

Picks your backend, configures API key, and generates codebase context — all in one step.

For TwelveLabs directly:

export TWELVE_LABS_API_KEY=your-key-here
eyeroll watch ./bug.mp4 --backend twelvelabs

Commands

Usage

In Claude Code

You: /eyeroll:watch https://loom.com/share/abc123
     → Analyzes video, presents: what's shown, the bug, key evidence, suggested fix

You: /eyeroll:fix https://loom.com/share/abc123
     → Watches video, greps codebase, finds the bug, fixes it, raises a PR

You: watch this tutorial and create a skill from it: ./demo.mp4
     → video-to-skill activates, watches video, generates SKILL.md

You: /eyeroll:history
     → Lists past analyses with timestamps and sources

Standalone CLI

eyeroll watch https://loom.com/share/abc123
eyeroll watch ./bug.mp4 --context "checkout broken after PR #432"
eyeroll watch ./bug.mp4 -cc .eyeroll/context.md --parallel 4
eyeroll watch ./bug.mp4 --backend ollama -m qwen3-vl:2b
eyeroll watch ./bug.mp4 --backend twelvelabs
eyeroll watch ./bug.mp4 --backend groq
eyeroll watch ./bug.mp4 --backend openrouter -m anthropic/claude-3.5-sonnet
eyeroll watch ./bug.mp4 --backend openai-compat --base-url https://my-server/v1
eyeroll watch ./bug.mp4 --no-context               # skip auto-discovery of codebase context
eyeroll watch ./bug.mp4 --no-cost                   # suppress cost estimate
eyeroll watch ./bug.mp4 --scene-threshold 50        # tune scene-change sensitivity
eyeroll watch ./bug.mp4 --min-audio-confidence 0.6  # stricter audio filtering
eyeroll history

How it works

/eyeroll:watch https://loom.com/share/abc123
    ↓
1. Preflight check (verify backend is reachable, detect capabilities)
    ↓
2. Download video (yt-dlp)
    ↓
3. Choose strategy:
   - Gemini API key: direct upload via File API (up to 2GB)
   - TwelveLabs: direct video understanding via Pegasus
   - Gemini service account: direct upload (up to 20MB)
   - OpenAI / OpenRouter / Groq: multi-frame batch (all frames in one call)
   - Ollama: frame-by-frame (one frame per call)
    ↓
4. Transcribe audio if present
    ↓
5. Cache intermediates (reuse on next run)
    ↓
6. Synthesize report with codebase context:
   - Metadata: intent, category, confidence, scope, repo guess, handoff recommendation
   - Bug, feature, question, docs, tutorial, review, or notes sections as appropriate
   - Agent handoff only when a code/docs/test/config change is actually useful
   - Search patterns and verification steps for coding agents when relevant
    ↓
7. Present summary to user
    ↓
/eyeroll:fix goes further:
   → grep codebase → read files → implement fix → run tests → PR

Backends

TwelveLabs uploads the video as an asset and asks Pegasus to generate the final structured report directly. It is intentionally not a frame-by-frame fallback backend; for videos beyond the direct-upload limits, use Gemini or OpenAI.

Ollama runs locally. Install and start Ollama separately, then eyeroll can pull the selected model on first use.

Codebase context

eyeroll automatically discovers codebase context from files like CLAUDE.md, AGENTS.md, CURSOR.md, and .eyeroll/context.md (disable with --no-context). You can also run /eyeroll:init to generate .eyeroll/context.md manually.

Without context, all file paths in the report are labeled as hypotheses.

Caching

eyeroll caches frame analyses and transcripts in ~/.eyeroll/cache/ (global). Same video = no re-analysis. Different --context re-runs only the cheap synthesis step. Legacy local .eyeroll/cache/ is still checked for backward compatibility.

eyeroll watch video.mp4                    # full analysis (~15s)
eyeroll watch video.mp4 -c "new context"   # instant — cached frames
eyeroll watch video.mp4 --no-cache         # force fresh

Cost estimates

eyeroll prints a cost estimate to stderr after each analysis. Disable with --no-cost. Ollama runs are always free.

Plugin structure

eyeroll/
  commands/              ← slash commands
    init.md              ← /eyeroll:init
    watch.md             ← /eyeroll:watch
    fix.md               ← /eyeroll:fix
    history.md           ← /eyeroll:history
  skills/                ← background skills
    video-to-skill/      ← activated by "create a skill from this video"
  eyeroll/               ← Python CLI package
    cli.py, watch.py, analyze.py, extract.py, backend.py, context.py, cost.py, history.py
  tests/                 ← unit, pipeline, server, MCP, and integration tests

Supported inputs

Development

git clone https://github.com/mnvsk97/eyeroll.git
cd eyeroll
pip install -e '.[dev,all,server]'
pytest                                                    # unit tests
pytest tests/test_integration.py -v -m integration        # real API tests

License

MIT