Skip to content
Back to search

claude-watch

MarketplaceWorks with Claude CodeGitHub

Give Claude the ability to watch any video — scene-change frames + transcript + a structured report, with a 0-10s hook microscope and optional Obsidian auto-save.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/taoufik123-collab--claude-watch/badge.svg)](/listings/taoufik123-collab--claude-watch)

HTML

<a href="/listings/taoufik123-collab--claude-watch"><img src="/api/listings/taoufik123-collab--claude-watch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| Surface | Install | |---------|---------| | **Claude Code** | `/plugin marketplace add taoufik123-collab/claude-watch` then `/plugin install watch@claude-watch` | | **claude.ai** (web) | [Download `watch.skill`](https://github.com/taoufik123-collab/claude-watch/releases/latest) → Settings → Capabilities → Skills → `+` | | **Codex** | `git clone https://github.com/taoufik123-collab/claude-watch.git ~/.codex/skills/watch` | | **Manual / dev** | `git clone https://github.com/taoufik123-collab/claude-watch.git ~/.claude/skills/watch` | | **Configuration** | Optional: `export WATCH_VAULT_DIR=/path/to/your/obsidian/vault` to enable auto-save. Auto-detects `~/Second brain/`, `~/Documents/Obsidian/`, `~/Obsidian/`. |

Claude Code

/plugin marketplace add taoufik123-collab/claude-watch
/plugin install watch@claude-watch

Update later with `/plugin update watch@claude-watch`.

claude.ai (web)

1. [Download `watch.skill`](https://github.com/taoufik123-collab/claude-watch/releases/latest) from the latest release. 2. Go to Settings → Capabilities → Skills. 3. Click `+` and drop the file in.

Enable "Code execution and file creation" under Capabilities first — the skill shells out to `ffmpeg` and `yt-dlp`, so it won't run without it.

Codex

git clone https://github.com/taoufik123-collab/claude-watch.git ~/.codex/skills/watch

Manual (developer)

git clone https://github.com/taoufik123-collab/claude-watch.git ~/.claude/skills/watch

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "claude-watch",
  3. "metadata": {
  4. "description": "Give Claude a video input. /watch downloads, extracts scene-change frames, microscopes the 0-10s hook, transcribes, and optionally auto-saves to your Obsidian vault."
  5. },
  6. "owner": {
  7. "name": "taoufik"
  8. },
  9. "plugins": [
  10. {
  11. "name": "watch",
  12. "description": "Watch a video (URL or local path). Downloads with yt-dlp, extracts scene-change frames with ffmpeg, runs a 0-10s hook microscope, transcribes via captions or Whisper, emits a structured report.md, optional Obsidian auto-save.",
  13. "author": {
  14. "name": "taoufik"
  15. },
  16. "source": "./",
  17. "category": "productivity",
  18. "homepage": "https://github.com/taoufik123-collab/claude-watch"
  19. }
  20. ]
  21. }
README.md · README · 224 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # /watch
  2. **Give Claude the ability to watch any video.**
  3. > Paste a URL or a local file and Claude *watches* it — **scene-change frame extraction** (one frame per cut instead of every-N-seconds), a **0-10s hook microscope** (dense frames + word-level Whisper on the opening, where every video earns or loses your attention), and **optional Obsidian auto-save** so a watched video becomes a connected wiki entry without copy-paste.
  4. **▶ Watch the skill in action** (this video is where `/watch` was born):
  5. [![This Claude Skill Watches Videos So You Don't Have To](https://img.youtube.com/vi/iYG5tiFfK3E/maxresdefault.jpg)](https://www.youtube.com/watch?v=iYG5tiFfK3E&t=43s)
  6. Claude Code:
  7. ```
  8. /plugin marketplace add taoufik123-collab/claude-watch
  9. /plugin install watch@claude-watch
  10. ```
  11. claude.ai (web): [download `watch.skill`](https://github.com/taoufik123-collab/claude-watch/releases/latest) and drop it into Settings → Capabilities → Skills.
  12. Codex / generic skills:
  13. ```bash
  14. git clone https://github.com/taoufik123-collab/claude-watch.git ~/.codex/skills/watch
  15. ```
  16. Zero config to start — `yt-dlp` and `ffmpeg` install on first run via `brew` on macOS (Linux/Windows print exact commands). Captions cover most public videos for free. Whisper API key is only needed when a video has no captions. Set `$WATCH_VAULT_DIR` to point at your Obsidian vault for auto-save, or leave it unset and the skill skips the ingest step quietly.
  17. ## What's inside
  18. - **Scene-change frame extraction** — `scripts/frames.py` grabs one frame per detected shot via ffmpeg's `select=gt(scene,...)`, not a uniform tick every N seconds. Token cost stays flat on long videos because the frame count is bounded by the number of cuts, not the duration.
  19. - **0-10s hook microscope** — `scripts/hook.py` runs a denser 2 fps pass on the opening 10 seconds plus a word-level Whisper transcript, so the report tells you what was on screen *as each word landed*. The first 10 seconds is where every video either earns your attention or loses it.
  20. - **Structured `report.md` with Claude-fill markers** — `scripts/report.py` emits a fixed-schema report (TL;DR, key moments, hook breakdown, editorial profile, quotable moments, entities, concepts, transcript) where narrative sections are explicit `<!-- pending Claude fill: ... -->` markers. Claude has a job-list to walk before ingest, not a blank doc.
  21. - **Optional Obsidian auto-save** — Step 4.4 stages the report into `$VAULT_DIR/raw/watched/<slug>/` and opens it via the `obsidian://` URL scheme. Step 4.5 offers ingest into the vault's wiki. Both steps skip cleanly when no vault is detected. Vault path is resolved from `$WATCH_VAULT_DIR` or auto-detected from `~/Second brain/`, `~/Documents/Obsidian/`, `~/Obsidian/`.
  22. The core pipeline — yt-dlp download, ffmpeg frames, Groq/OpenAI Whisper backends, the `--start`/`--end` focused mode, the SessionStart hook, the multi-surface install — comes from the original `claude-video` project and works unchanged (see [Credits](#credits)).
  23. ---
  24. Claude can read a webpage, run a script, browse a repo. What it can't do, out of the box, is *watch a video*. You paste a YouTube link and it has to either guess from the title or pull a transcript that's missing 90% of what's on screen.
  25. With Claude Video `/watch` you can paste a URL or a local path, ask a question, and Claude downloads the video, extracts frames at an auto-scaled rate, pulls a timestamped transcript (free captions when available, Whisper API as fallback), and `Read`s every frame as an image. By the time it answers, it has *seen* the video and *heard* the audio.
  26. ```
  27. /watch https://youtu.be/iYG5tiFfK3E how does this creator hook the viewer in the first 45 seconds?
  28. ```
  29. ## Why this exists
  30. I built this because I'm constantly using video to keep up with content. If I see a YouTube video that's blowing up, I want to know how the creator structured the hook — what's on screen in the first 3 seconds, what they said, why it worked. That used to mean watching it myself with a notepad. Now I just paste the URL and ask.
  31. The other half is summarization. Most YouTube videos don't deserve 20 minutes of my attention. I hand the URL to Claude, it pulls the transcript, and tells me what actually happened. If the visual matters, frames come along too. If it's a podcast or a talking head, transcript is enough.
  32. Claude is great at reading and synthesizing — but until now, video was the one input I couldn't hand it. Pasting a YouTube link got you nothing useful. `/watch` closes that gap.
  33. ## What people actually use it for
  34. **Analyze someone else's content.** `/watch https://youtu.be/<viral-video> what hook did they open with?` Claude looks at the first frames, reads the opening transcript, breaks down the structure. Same for ad creative, competitor launches, podcast intros, anything where the *how* matters as much as the *what*.
  35. **Diagnose a bug from a video.** Someone sends you a screen recording of something broken. `/watch bug-repro.mov what's going wrong?` Claude watches the recording, finds the frame where the issue appears, describes what's on screen, often catches the cause without you ever opening the file.
  36. **Summarize a video.** `/watch https://youtu.be/<long-thing> summarize this` does the obvious thing — pulls the structure, the key moments, what was actually said and shown. Faster than watching at 2x.
  37. ## How it works
  38. 1. **You paste a video and a question.** URL (anything yt-dlp supports — YouTube, Loom, TikTok, X, Instagram, plus a few hundred more) or a local path (`.mp4`, `.mov`, `.mkv`, `.webm`).
  39. 2. **`yt-dlp` downloads it.** For URLs, into a temp working directory. For local files, no download — just probed in place.
  40. 3. **`ffmpeg` extracts frames at an auto-scaled rate.** The frame budget is duration-aware: ≤30s gets ~30 frames, 30-60s gets ~40, 1-3min gets ~60, 3-10min gets ~80, longer gets 100 sparsely. Hard ceilings: 2 fps, 100 frames. JPEGs at 512px wide by default — bump with `--resolution 1024` if Claude needs to read on-screen text.
  41. 4. **The transcript comes from one of two places.** First try: `yt-dlp` pulls native captions (manual or auto-generated) from the source. Free, instant, accurate-ish. Fallback: extract a mono 16 kHz audio clip and ship it to Whisper — Groq's `whisper-large-v3` (preferred — cheaper and faster) or OpenAI's `whisper-1`.
  42. 5. **Frames + transcript are handed to Claude.** The script prints frame paths with `t=MM:SS` markers and the transcript with timestamps. Claude `Read`s each frame in parallel — JPEGs render directly as images in its context.
  43. 6. **Claude answers grounded in what's actually on screen and in the audio.** Not "based on the description" or "according to the title." It saw the frames. It heard the transcript. It answers the way someone who watched the video would.
  44. 7. **Cleanup.** The script prints a working directory at the end. If you're not asking follow-ups, Claude removes it.
  45. ## Frame budget — why it matters
  46. Token cost is dominated by frames. Every frame is an image; image tokens add up fast. The script's auto-fps logic exists so you don't blow your context budget on a sparse scan of a 30-minute video that would have been better answered by a focused 30-second window.
  47. | Duration | Default frame budget | What you get |
  48. |----------|---------------------|--------------|
  49. | ≤30 s | ~30 frames | Dense — basically every key moment |
  50. | 30 s - 1 min | ~40 frames | Still dense |
  51. | 1 - 3 min | ~60 frames | Comfortable |
  52. | 3 - 10 min | ~80 frames | Sparse but workable |
  53. | > 10 min | 100 frames | "Sparse scan" warning — re-run focused |
  54. When the user names a moment ("around 2:30", "the last 30 seconds", "from 0:45 to 1:00"), pass `--start` / `--end`. Focused mode gets denser per-second budgets, capped at 2 fps. Far more useful than a sparse pass over the whole thing.
  55. ## Install
  56. | Surface | Install |
  57. |---------|---------|
  58. | **Claude Code** | `/plugin marketplace add taoufik123-collab/claude-watch` then `/plugin install watch@claude-watch` |
  59. | **claude.ai** (web) | [Download `watch.skill`](https://github.com/taoufik123-collab/claude-watch/releases/latest) → Settings → Capabilities → Skills → `+` |
  60. | **Codex** | `git clone https://github.com/taoufik123-collab/claude-watch.git ~/.codex/skills/watch` |
  61. | **Manual / dev** | `git clone https://github.com/taoufik123-collab/claude-watch.git ~/.claude/skills/watch` |
  62. | **Configuration** | Optional: `export WATCH_VAULT_DIR=/path/to/your/obsidian/vault` to enable auto-save. Auto-detects `~/Second brain/`, `~/Documents/Obsidian/`, `~/Obsidian/`. |
  63. ### Claude Code
  64. ```
  65. /plugin marketplace add taoufik123-collab/claude-watch
  66. /plugin install watch@claude-watch
  67. ```
  68. Update later with `/plugin update watch@claude-watch`.
  69. ### claude.ai (web)
  70. 1. [Download `watch.skill`](https://github.com/taoufik123-collab/claude-watch/releases/latest) from the latest release.
  71. 2. Go to Settings → Capabilities → Skills.
  72. 3. Click `+` and drop the file in.
  73. Enable "Code execution and file creation" under Capabilities first — the skill shells out to `ffmpeg` and `yt-dlp`, so it won't run without it.
  74. ### Codex
  75. ```bash
  76. git clone https://github.com/taoufik123-collab/claude-watch.git ~/.codex/skills/watch
  77. ```
  78. ### Manual (developer)
  79. ```bash
  80. git clone https://github.com/taoufik123-collab/claude-watch.git ~/.claude/skills/watch
  81. ```
  82. ## First run
  83. On the first `/watch` call, the skill runs `scripts/setup.py --check`. If `ffmpeg` / `yt-dlp` aren't on your PATH, or no Whisper API key is set, it walks you through fixing it:
  84. - **macOS** — auto-runs `brew install ffmpeg yt-dlp`.
  85. - **Linux** — prints the exact `apt` / `dnf` / `pipx` commands.
  86. - **Windows** — prints the `winget` / `pip` commands.
  87. - **API key** — scaffolds `~/.config/watch/.env` (mode `0600`) with commented placeholders for `GROQ_API_KEY` (preferred) and `OPENAI_API_KEY`.
  88. After setup, preflight is silent and `/watch` just works. The check is a sub-100ms lookup, so it doesn't slow you down on subsequent runs.
  89. ## Bring your own keys
  90. Captions cover the majority of public videos for free. The Whisper fallback only kicks in when a video genuinely has no caption track — typically local files, TikToks, some Vimeos, and the occasional caption-less YouTube upload.
  91. | Capability | What you need | Cost |
  92. |------------|---------------|------|
  93. | Download + native captions | `yt-dlp` + `ffmpeg` | Free |
  94. | Whisper fallback (preferred) | [Groq API key](https://console.groq.com/keys) — `whisper-large-v3` | Cheap, fast |
  95. | Whisper fallback (alt) | [OpenAI API key](https://platform.openai.com/api-keys) — `whisper-1` | Standard pricing |
  96. | Disable Whisper entirely | `--no-whisper` | Free, frames-only when no captions |
  97. ## Usage
  98. ```
  99. /watch https://youtu.be/iYG5tiFfK3E how does this creator hook the viewer in the first 45 seconds?
  100. /watch https://www.tiktok.com/@user/video/123 summarize this
  101. /watch ~/Movies/screen-recording.mp4 when does the UI break?
  102. /watch https://vimeo.com/123 what tools does she mention?
  103. ```
  104. Focused on a specific section — denser frame budget, lower token cost:
  105. ```
  106. /watch https://youtu.be/abc --start 2:15 --end 2:45
  107. /watch video.mp4 --start 50 --end 60
  108. /watch "$URL" --start 1:12:00 # from 1h12m to end
  109. ```
  110. Other knobs (passed to `scripts/watch.py`):
  111. - `--max-frames N` — lower the frame cap for a tighter token budget.
  112. - `--resolution W` — bump frame width to 1024 px when Claude needs to read on-screen text (slides, terminals, code).
  113. - `--fps F` — override the auto-fps calculation (still capped at 2 fps).
  114. - `--whisper groq|openai` — force a specific Whisper backend.
  115. - `--no-whisper` — disable transcription entirely; frames only.
  116. - `--out-dir DIR` — keep working files somewhere specific (default: auto-generated tmp dir).
  117. ## Limits
  118. - **Best accuracy: under 10 minutes.** Past that the script prints a "sparse scan" warning — re-run focused on the part you actually care about with `--start`/`--end`.
  119. - **Hard caps: 2 fps, 100 frames.** Frame count drives token cost; the script enforces this even when the auto-fps math would imply higher.
  120. - **Whisper upload limit: 25 MB.** At mono 16 kHz that's about 50 minutes of audio. Longer videos need either captions or `--start`/`--end` to a smaller window.
  121. - **No private platforms.** This skill doesn't log into anything. Public URLs and local files only. If yt-dlp can't reach it without auth, neither can `/watch`.
  122. ## Structure
  123. ```
  124. .
  125. ├── SKILL.md # skill contract — loaded by all three surfaces
  126. ├── scripts/
  127. │ ├── watch.py # entry point — orchestrates download → frames → transcript
  128. │ ├── download.py # yt-dlp wrapper
  129. │ ├── frames.py # ffmpeg frame extraction + auto-fps logic
  130. │ ├── transcribe.py # VTT parsing + dedupe + Whisper orchestration
  131. │ ├── whisper.py # Groq / OpenAI clients (pure stdlib)
  132. │ ├── setup.py # preflight + installer
  133. │ └── build-skill.sh # build dist/watch.skill for claude.ai upload
  134. ├── hooks/ # SessionStart status hook (Claude Code only)
  135. ├── .claude-plugin/ # plugin.json + marketplace.json (Claude Code)
  136. ├── .codex-plugin/ # codex packaging
  137. └── .github/workflows/ # release.yml — auto-builds watch.skill on tag push
  138. ```
  139. ## Develop
  140. ```bash
  141. # Build the claude.ai upload bundle:
  142. bash scripts/build-skill.sh # → dist/watch.skill
  143. ```
  144. Releasing: tag `vX.Y.Z`, push the tag. The workflow builds `dist/watch.skill` and attaches it to the GitHub release.
  145. See [CHANGELOG.md](CHANGELOG.md) for version history.
  146. ## Who made this
  147. I'm Taoufik. I build AI agents and tools like `/watch`, and I make videos about how I build them: **[@TaoufikAI on YouTube](https://www.youtube.com/@TaoufikAI)**. If this skill saved you time, the channel is where the next ones show up first. [Subscribe here.](https://www.youtube.com/@TaoufikAI?sub_confirmation=1)
  148. ## Credits
  149. Built on the original `claude-video` project, MIT licensed. Full attribution in [AUTHORS.md](AUTHORS.md) and [LICENSE](LICENSE).
  150. ## Open source
  151. MIT license.
  152. Built on `yt-dlp`, `ffmpeg`, and Claude's multimodal `Read` tool. Whisper transcription via [Groq](https://groq.com) or [OpenAI](https://openai.com).
  153. ---
  154. [github.com/taoufik123-collab/claude-watch](https://github.com/taoufik123-collab/claude-watch) · [Credits](#credits) · [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.