claude-watch budgets frames by scene cuts, and names its vault variable two different ways

The vault variable is named two ways on the same page

The Obsidian feature is genuinely well described, and it contains an inconsistency in the one thing you need to type.

The introduction says to set a `WATCH_VAULT_DIR` variable to point at your vault. The feature description two sections later refers to the same setting as `VAULT_DIR`, twice. Both appear on the page, and nothing states that the second is shorthand for the first.

The behaviour around a missing vault is the other thing to know. If the variable is unset, the skill skips the ingest step quietly. The two ingestion steps are described in the feature list with step numbers, so the pipeline has a fixed shape: one step stages the report into a directory under the vault named `raw/watched/<slug>/` and opens it through an Obsidian URL scheme, and the next step offers to ingest it into the vault's wiki. Both steps skip cleanly when no vault is detected.

Quiet skipping is a defensible choice for an optional integration, and it is also the kind that hides a configuration mistake. A typo in either variable name and the symptom is identical to not using Obsidian at all.

For the path itself there is a fallback chain. The vault is resolved from the variable when set, and otherwise auto-detected from three well known locations: a directory named Second brain under the home directory, an Obsidian directory under Documents, and an Obsidian directory directly under home. So a standard layout works with no configuration, and a non-standard one needs the variable spelled the way the introduction spells it.

The frame budget counts cuts, not seconds

The extraction strategy is the part that differs from a naive sampler, and it is one line of ffmpeg.

The frame script grabs one frame per detected shot using ffmpeg's scene change filter, described as selecting where the scene value is greater than a threshold. It is explicitly not a uniform tick every N seconds. The consequence is stated as a cost property: token cost stays flat on long videos because the frame count is bounded by the number of cuts rather than by the duration.

For the general case the sampling is duration aware, with a table of buckets. A clip of thirty seconds or less gets about thirty frames, thirty to sixty seconds gets about forty, one to three minutes about sixty, three to ten minutes about eighty, and anything longer gets a hundred frames spread sparsely. Two hard ceilings apply on top: two frames per second and a hundred frames.

So there are two mechanisms working together. Scene cuts determine placement, and the duration table determines the ceiling, and the hard limits catch the cases where either would overshoot.

Resolution is a separate dial. Frames are written as JPEGs at 512 pixels wide by default, with a flag to raise it to 1024 when the model needs to read text on screen. That is the right default, since most video does not need legible on-screen text and image tokens are the dominant cost.

For the opening, the sampling rule is different again, and that is what the dedicated hook script is for.

The opening ten seconds get a denser pass and a word-level transcript

One window of the video is treated specially, and the reasoning is given.

A dedicated script runs a denser pass at two frames per second over the opening ten seconds, together with a word-level speech transcript for the same window. The stated purpose is that the report can then say what was on screen as each word landed, rather than at the granularity of a sentence.

The justification is a claim about attention rather than about modelling: the first ten seconds is where every video either earns your attention or loses it.

That framing explains why the feature exists and also where its limits are. The window is fixed at ten seconds, so the hook analysis is not configurable, and the sample example asks a question about the first forty five seconds. The first ten seconds are examined densely; anything between ten and forty five seconds is left to whatever the main extraction produced for that region.

The word-level part comes from the same transcription path as the rest of the transcript, but at a different granularity. The main transcript is described as timestamped, while this one is word-level and limited to the opening, which is the smallest useful unit for asking when something was said relative to when it appeared.

The use cases the page lists lean on this heavily. Breaking down how a creator opened a video, analysing ad creative, competitor launches and podcast intros are all questions about the first seconds, and they are the questions the hook pass was built to answer.

The report is a fixed schema with explicit markers, not a blank document

The report generator is the piece that decides what the assistant has to fill in, and it is a schema rather than a template.

A script emits a fixed-schema report with a named set of sections: a summary line, key moments, the hook breakdown, an editorial profile, quotable moments, entities, concepts, and the transcript. The narrative sections are not empty. They contain explicit markers of the form a pending Claude fill comment, naming what is expected in each.

The reasoning is stated plainly: Claude has a job list to walk before ingest, not a blank document. That is a real difference in how a model approaches the task. With a blank page it decides what is worth writing and may skip a section entirely; with a list of named fields it fills each one, and a missing section is visible as a marker left unfilled.

The editorial profile and quotable moments entries are the two that have no mechanical equivalent. Neither can be derived from frames or timestamps, so both are marked for the model to write, which means the quality of the final report depends on the model rather than on the pipeline.

Entities and concepts are the opposite: they are inventory sections, and they sit alongside the transcript, which is copied rather than written.

This is also why the ingest step into the vault is described as happening after the fill rather than during it. The staged file is a structured document by the time it lands in the vault.

Captions first, a paid speech API second

The transcript has a definite order of preference, and the free path is the one that normally runs.

The script first asks the downloader for native captions from the source, whether those are manual or auto-generated. That is described as free, instant and reasonably accurate, and the page states that captions cover most public videos for free.

Only if that fails does the fallback run. It extracts a mono 16 kHz audio clip and sends it to a speech API. Two backends are named, with the Groq large v3 model preferred and described as both cheaper and faster, and the OpenAI model as the alternative. An API key is needed only in this branch, which is stated as a requirement rather than a default.

That two tier structure is worth internalising because it changes what you have to set up. A user watching public videos needs a downloader, an encoder and nothing else. A user watching a private local recording with no caption track needs one of two API keys.

The frame and transcript data are then handed over together. The script prints frame paths with markers showing the time offset in minutes and seconds, and prints the transcript with timestamps. The assistant reads each frame as an image, in parallel, and the frames are JPEGs, which render directly in the model's context.

Local files skip the download entirely and are probed in place, which is the path a screen recording takes.

Three install surfaces, two plugin manifests, and dependencies fetched on first run

The skill is distributed for three different hosts, and each has its own install line.

For a coding agent the repository is a plugin, installed from inside the tool with two commands: one adds the repository as a marketplace and the other installs the plugin from it. The plugin is named `watch` and the marketplace identifier is derived from the repository.

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

For the web interface the distribution is a single skill file, downloaded from the project's releases and dropped into a settings path under capabilities and skills. That is a file move rather than a clone.

For a different agent or a generic skills directory it is a clone into a skills folder in the home directory. The target path is a directory named after the skill.

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

The tree matches those three surfaces. There are two plugin manifest directories, one for each plugin format, alongside the skill definition file, a commands directory, a hooks directory and a scripts directory. Having both manifest directories committed is what lets one repository serve two plugin ecosystems.

The dependencies are handled unusually. The downloader and the encoder install themselves on first run through a package manager on macOS, and on Linux and Windows the scripts print the exact commands rather than running anything. So the zero configuration claim is specifically true on macOS and becomes a printed instruction elsewhere.

The invocation itself is one command with a URL and a question, so the question is part of the call rather than something asked afterwards. The page names several supported sources through the downloader and four local container formats.

The pipeline is inherited, and the repository says which parts

The last section of the feature list is the credit, and it is unusually specific about scope.

The core pipeline comes from an earlier project and works unchanged. The listed inherited pieces are the downloader step, the frame extraction, both speech backends, a focused mode built around start and end markers, a session start hook, and the multi-surface installation. Those are six things, and they are the parts of the pipeline a new user touches first.

So what is new here is the part the page leads with: scene-change extraction as the default rather than a rate, the opening ten second microscope, the fixed-schema report, and the vault integration.

That division is stated in the repository itself rather than only in prose. There is an authors file at the root, a changelog, and a credits anchor on the page, and the pipeline section says which project the code started from.

Release history is thin, which is consistent with a project that started as a fork of a described ancestor. There is a single tagged release at 0.2.0 from 2026-05-25, and the last push to the default branch is recorded as 2026-07-24.

One operational detail closes the loop on cleanup. The script prints the working directory it worked in, and if there are no follow-up questions the assistant removes it. So the video, the frames and the audio clip are left behind on purpose for the length of one session and cleaned up at the end of it, which is also why the download for a URL goes into a temporary directory in the first place.

Editorial conclusion

This is worth installing if your question about a video is about what was on screen rather than what was said, because the scene-cut extraction is what makes it different from reading a transcript, and the opening ten second pass is the part that answers hook questions. Two things to check. The Obsidian path is described with two different names for its environment variable, so read both before you conclude the vault was not found, and note that a missing vault is skipped quietly rather than reported. And the core pipeline comes from an earlier project that is credited in place, which means the download, frame and transcript stages are inherited rather than written here, so you should check that project's own terms before depending on them. For copyright, use this on material you are allowed to process.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. taoufik123-collab/claude-watch on GitHub