LaLeV/claude-video
1
0
Fork 0
mirror of https://github.com/Luchexx/claude-video.git synced 2026-11-02 09:19:48 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: point Claude users to Claude Code and offer to open the config for keys

Browse Source 
The README now says Watch runs in Claude Code (Desktop's Code tab, VS
Code, or a terminal) and does not work in Claude Chat or Cowork. Cowork's
cloud environment drops the Gemini key between tasks and most sites block
yt-dlp from it. The standalone Chat upload instructions are removed.

Setup lets the user choose how to add an API key: paste it in chat, or
have the agent open ~/.config/watch/.env in their editor.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
bradautomates 2026-09-25 11:25:31 +10:00
parent 7f288b4400
commit 7948897be8
2 changed files with 24 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -1,23 +1,23 @@
# /watch
Give an agent video evidence: a URL or local file becomes timestamped frames and a transcript. Install it in Claude Desktop for Cowork or Code, or use it with Codex and other [Agent Skills](https://agentskills.io) hosts. Native captions come first; optional local WhisperX or Groq/OpenAI transcription handles videos without captions.
Give an agent video evidence: a URL or local file becomes timestamped frames and a transcript. Install it in Claude Code (the desktop app, VS Code, or a terminal), or use it with Codex and other [Agent Skills](https://agentskills.io) hosts. Native captions come first; optional local WhisperX or Groq/OpenAI transcription handles videos without captions.
## Choose your app
**Using Claude? Run Watch in Cowork or Code.** The plugin is not used in regular Chat. For a first setup, use one of the desktop paths below; [browser sessions have extra limitations](#using-a-web-app).
**Using Claude? Run Watch in Claude Code.** Install it through Claude Desktop and use a **Code** session, or add it with the plugin commands in VS Code or a terminal. Watch does **not** work in Claude Chat or Cowork; [see why](#chat-cowork-and-browser-apps).
| Where you use your agent | Start here |
|---|---|
| **Claude Desktop — Cowork or Code** | [Install through Customize](#claude-desktop--cowork-or-code) — no terminal needed |
| **Claude Desktop — Code** | [Install through Customize](#claude-desktop--code) — no terminal needed |
| **Codex — desktop app, CLI, or IDE extension** | [Ask Codex to install it](#codex) — no terminal needed |
| **Claude Code in VS Code** | [Use the extension's plugin window](#claude-code-in-vs-code) |
| **Claude Code in a terminal** | [Enter the plugin commands](#claude-code-in-a-terminal) |
| **Cursor, Copilot, or another local agent** | [Use the Skills CLI](#other-local-agents) |
| **Claude or ChatGPT in a browser** | [Check the supported mode and limitations](#using-a-web-app) |
| **Claude Chat, Cowork, or a browser app** | [Chat and Cowork don't work; browser apps have limits](#chat-cowork-and-browser-apps) |
Choose **one installation method** for your agent. If Watch is already installed, go straight to [your first video](#try-your-first-video).
### Claude Desktop — Cowork or Code
### Claude Desktop — Code
1. Open **Claude Desktop** and click **Customize** in the sidebar.
2. Select **Plugins**, open **Add**, then choose **Add marketplace**.
@ -37,7 +37,7 @@ https://github.com/bradautomates/claude-video
![Marketplace URL form filled with the public claude-video GitHub address and a Sync button](docs/images/install/claude-marketplace-url.png)
5. Find **Watch** in the added marketplace and install it. Adding the marketplace alone does not install Watch.
6. Start a **Cowork** task or a **Code** session and ask it to use the watch skill. Continue with [your first video](#try-your-first-video).
6. Start a **Code** session and ask it to use the watch skill. Watch does not work in Cowork tasks ([why](#chat-cowork-and-browser-apps)). Continue with [your first video](#try-your-first-video).
If you do not see these controls, update Claude Desktop. On a managed account, your administrator may control which plugins you can add. See the [official plugin guide](https://claude.com/docs/cowork/guide/plugins).
@ -123,17 +123,17 @@ For other [Agent Skills hosts](https://agentskills.io), install [Node.js](https:
npx skills add bradautomates/claude-video -g --skill watch
```
Select your agent when prompted, follow the installer's reported destination, then restart the agent. Node/npm is needed for this installer, not for Watch's Python runtime. This command does not install Watch into Claude Desktop's Cowork environment.
Select your agent when prompted, follow the installer's reported destination, then restart the agent. Node/npm is needed for this installer, not for Watch's Python runtime.
You can target an agent explicitly, for example `-a codex`, but Codex users can use the simpler [message-box installation](#codex). See the [Skills CLI documentation](https://github.com/vercel-labs/skills).
## Try your first video
**Fastest path — let Gemini watch it.** Add a free [Google AI Studio key](https://aistudio.google.com/apikey) when the setup wizard asks (or put `GEMINI_API_KEY=...` in `~/.config/watch/.env`). Watch then hands the whole video — picture and sound — to Google's agentic video model and relays its timestamped answer. YouTube links need nothing else installed. Local files are uploaded to Google and deleted after the answer.
**Fastest path — let Gemini watch it.** Get a free [Google AI Studio key](https://aistudio.google.com/apikey). When the setup wizard asks for it, paste it in the chat, or have the agent open `~/.config/watch/.env` in your text editor so you can paste it after `GEMINI_API_KEY=` and save it yourself. Watch then hands the whole video — picture and sound — to Google's agentic video model and relays its timestamped answer. YouTube links need nothing else installed. Local files are uploaded to Google and deleted after the answer.
**No key, or a private video?** Choose `local`. Watch extracts frames and a transcript on your machine (`ffmpeg` + `yt-dlp`), exactly as before. Force it any time with `--engine local`. The walkthrough below uses this no-key path.
1. Give your agent access to a folder containing a **short video**, such as `example.mp4`. In Cowork, connect that folder; in a coding agent, open the folder as your project. Replace the filename below with your own.
1. Give your agent access to a folder containing a **short video**, such as `example.mp4`. Open that folder as your agent's project. Replace the filename below with your own.
2. Paste this **into the agent's message box**:
```text
@ -161,7 +161,7 @@ Use the watch skill's bundled setup.py to check dependencies in this session.
Tell me which tools are missing and help me install them here.
```
**Cowork and cloud sessions:** let the agent check inside its execution environment. Installing FFmpeg with Homebrew on your Mac does not install it inside Cowork's Linux VM or cloud sandbox. Package and network permissions may require administrator help. A new cloud task may also need setup again. [Cowork architecture](https://support.claude.com/en/articles/14479288-claude-cowork-architecture-overview)
**Cloud sessions** (such as Claude Code on the web): let the agent check inside its execution environment. Installing FFmpeg with Homebrew on your Mac does not install it inside a cloud sandbox. Package and network permissions may require administrator help. A new cloud task may also need setup again.
**Agents running directly on your computer:** Watch can install missing media tools through Homebrew on macOS. On other systems it supplies commands. If manual installation is needed, run the appropriate commands in a terminal:
@ -173,29 +173,18 @@ Tell me which tools are missing and help me install them here.
Reopen the terminal and agent after installation so they can find the new tools. On Windows, verify Python with `python --version` or `py -3 --version`. Watch supports the **latest yt-dlp release** only, because sites routinely break older ones; it uses the executable available in the active environment.
## Using a web app?
## Chat, Cowork, and browser apps
For the easiest first setup, use [Claude Desktop](#claude-desktop--cowork-or-code) or [Codex locally](#codex).
**Watch works in Claude Code:** a **Code** session in [Claude Desktop](#claude-desktop--code), or Claude Code installed with the plugin commands in [VS Code](#claude-code-in-vs-code) or [a terminal](#claude-code-in-a-terminal). Codex and other [local agents](#other-local-agents) work too.
| Browser surface | What to know |
| Surface | What to know |
|---|---|
| **Regular Claude Chat** | Watch's plugin is used in Cowork or Code. Uploading a standalone skill to Chat does not remove sandbox network restrictions. |
| **Cowork on the web** | Select **Cowork** in the message box. Current Cowork supports skills/plugins on the web, but Watch still needs working tools and permitted access to video, API, and model hosts. Its full workflow has not been verified here. |
| **Claude Chat** | Not supported, including uploading `watch.skill` as a custom skill. |
| **Cowork** (desktop or web) | Not supported. Cowork runs Watch in a cloud environment. The [Gemini engine](#choose-an-engine) can run there, but your `GEMINI_API_KEY` doesn't persist between tasks. The local engine can't fetch most URLs, because most sites block yt-dlp downloads from that environment. |
| **Claude Code on the web** | Uses a cloud environment with its own setup and network settings. The interactive `/plugin` installer is unavailable there. The terminal walkthrough above is for local Claude Code. |
| **ChatGPT/Codex browser surfaces** | Attaching `watch.skill` to a chat is not a local Codex installation. Use the Codex installer above; a public/workspace plugin listing is a separate distribution route. |
See the official guides for [Cowork on web and desktop](https://support.claude.com/en/articles/15520349-use-claude-cowork-on-web-desktop-and-mobile), [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web), and [OpenAI plugin surfaces](https://learn.chatgpt.com/docs/plugins).
<details>
<summary>Advanced: standalone skill upload in Claude</summary>
This is a conditional route, not the recommended beginner setup. Enable code execution, then use **Customize → Skills → + → Create skill → Upload a skill**. See [Claude's custom-skill instructions](https://support.claude.com/en/articles/12512180-use-skills-in-claude).
[Releases](https://github.com/bradautomates/claude-video/releases/latest) include `watch.skill`, a ZIP-format archive of the skill folder. If the picker requires a `.zip` extension, make a copy named `watch.zip`. The current picker's acceptance of this release artifact has not been verified. GitHub's **Source code (zip)** is the whole repository, not the skill package. Use **Upload a skill**, not **Upload plugin**.
A successful upload does not establish a working video pipeline. The hosted environment may run programs while blocking video/CDN/API/model downloads. Check the account's [execution and network settings](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude). An accessible local file avoids its download, but speech transcription may still require permitted network access.
</details>
See the official guides for [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) and [OpenAI plugin surfaces](https://learn.chatgpt.com/docs/plugins).
## Choose an engine

11
skills/watch/SKILL.md
View File

@ -40,13 +40,18 @@ python3 "${SKILL_DIR}/scripts/setup.py" --json
- `gemini` (recommended) — Google's Gemini model watches the whole video, including audio, and answers directly. Needs a free key from https://aistudio.google.com/apikey. YouTube URLs are sent to Google; local or downloaded videos are uploaded to Google, then deleted after the answer.
- `local` — frames + transcript extracted on this machine and read by you. No key needed.
If `gemini`: ask for the key or have the user add `GEMINI_API_KEY=` privately to `~/.config/watch/.env` (never print it or put it in a shell command), then run:
If `gemini`, run:
```bash
python3 "${SKILL_DIR}/scripts/setup.py" --engine gemini
```
Exit 3 means the key is still missing (the first run also scaffolds the config file to put it in). On exit 0 setup is complete — **skip the detail and transcription questions**; they only apply to the local engine. If `local`: run `setup.py --engine local` (this also installs missing base binaries and scaffolds the private config) and continue with the two questions below. An existing explicit `WATCH_ENGINE` is not asked again.
Exit 3 means the key is missing; the command has created `~/.config/watch/.env` for it. Point the user to https://aistudio.google.com/apikey for a free key and let them choose how to add it:
- **Paste it in chat.** Write it on the `GEMINI_API_KEY=` line of the config file (add the line if it is missing) with a file-editing tool, preserving the other lines.
- **Add it themselves.** Offer to open the config file in their text editor (`open -t` on macOS, `notepad` on Windows, `xdg-open` on Linux) so they can paste the key after `GEMINI_API_KEY=` and save. This only works when you run on the user's own computer; otherwise give them the file path.
Never print the key or put it in a shell command. Once it is saved, rerun `setup.py --engine gemini`. On exit 0 setup is complete — **skip the detail and transcription questions**; they only apply to the local engine. If `local`: run `setup.py --engine local` (this also installs missing base binaries and scaffolds the private config) and continue with the two questions below. An existing explicit `WATCH_ENGINE` is not asked again.
Ask for the default detail, lightest to heaviest:
@ -75,7 +80,7 @@ python3 "${SKILL_DIR}/scripts/setup.py" --backend whisperx --detail balanced
For WhisperX, relay progress while the installer provisions uv, Python 3.12, pinned dependencies, and both model caches. `setup.py --install-whisperx` reruns this managed installer if needed. It writes the backend, executable, model, and completion marker only after warm-up succeeds. A failed local installation never selects a cloud backend automatically.
For cloud, ask for the matching key or have the user enter it privately in `~/.config/watch/.env`, then rerun `setup.py --backend groq` or `--backend openai`. Preserve existing keys and comments; do not print keys or include them in a shell command. The script marks setup complete after that backend is ready. `--backend none` needs no key and completes immediately.
For cloud, get the matching key the same way as the Gemini key (pasted in chat, or the user adds it after offering to open the config file), then rerun `setup.py --backend groq` or `--backend openai`. Preserve existing keys and comments; do not print keys or include them in a shell command. The script marks setup complete after that backend is ready. `--backend none` needs no key and completes immediately.
`setup.py --check` is a fast, silent base preflight: exit 0 when binaries exist (or the Gemini engine is active), 2 for missing dependencies/config errors. It never starts Torch or queries network services. `--json` adds `engine` (resolved: `gemini` or `local`), `configured_engine`, `gemini_key_present` (boolean only), `gemini_model`, `binaries_required`, executable paths/versions, offline yt-dlp capability diagnostics, and `whisperx_ready`, `whisperx_bin`, `whisperx_model`, and `backend_ready`. Local readiness in detailed mode checks the sentinel and executable help. Optional fallback failure does not block base watch.