taoufik123-collab/claude-watch

1. This repo is a local Claude skill/plugin, not a web service.

The architecture is centered on shelling out from Claude Code / claude.ai / Codex to local Python scripts. There is no persistent backend; each /watch run is an isolated pipeline execution on the user’s machine.

2. Three packaging surfaces share one core skill contract.

SKILL.md is the common entrypoint text. The repo also includes .claude-plugin/ and .codex-plugin/ manifests for platform-specific installation, plus commands/watch.md for the command surface. The same underlying behavior is packaged differently for Claude Code, claude.ai skills, and Codex skills.

3. The main orchestration boundary is scripts/watch.py.

This is the top-level driver that coordinates the workflow: resolve input, download or inspect the media, extract frames, get a transcript, and assemble output for Claude. It is the central integration point between all other subsystems.

4. Media acquisition is handled by scripts/download.py via yt-dlp.

This layer is responsible for both remote URLs and local-file handling. For URLs it downloads into a working directory; for local files it probes in place. This is the boundary between “user input” and “analysis-ready media.”

5. Visual analysis is a dedicated ffmpeg subsystem in scripts/frames.py.

The repo’s key architectural differentiation is that frames are not sampled uniformly. Instead, frames.py uses scene-change extraction plus duration-aware auto-scaling, with hard caps on fps and total frame count. This keeps image-token cost bounded and makes the output structure depend on content cuts, not runtime length.

6. Focused opening analysis is a separate visual/audio path in scripts/hook.py and scripts/pacing.py.

The “0–10s hook microscope” is treated as a special case: denser frame extraction for the opening segment plus transcript timing support. pacing.py suggests a dedicated concern for rate/budget calculation, especially for the opening attention-critical window.

7. Transcription is a two-stage subsystem in scripts/transcribe.py and scripts/whisper.py.

The first preference is native captions retrieved through yt-dlp. If captions are unavailable, the pipeline falls back to Whisper transcription, with whisper.py acting as the service client boundary. The repo supports Groq and OpenAI backends, with Groq preferred for cost/speed. --no-whisper cleanly disables this branch.

8. Structured output is generated by scripts/report.py.

Rather than producing only freeform text, the repo builds a fixed-schema report.md with sections like TL;DR, key moments, hook breakdown, editorial profile, entities, concepts, and transcript. The <!-- pending Claude fill: ... --> markers indicate an intentional handoff between scripted extraction and Claude’s narrative synthesis.

9. There is an optional Obsidian vault ingest path.

The pipeline can stage watched-video notes into a vault under raw/watched/<slug>/ and open them through the obsidian:// scheme. This is gated by WATCH_VAULT_DIR or auto-detection of common vault locations, and it is designed to fail silently when no vault is present.

10. Environment/bootstrap concerns are isolated in scripts/setup.py and the hook checks.

First-run setup validates ffmpeg, yt-dlp, and Whisper API credentials, and may install dependencies on macOS via Homebrew. hooks/hooks.json and hooks/scripts/check-setup.sh define a Claude Code SessionStart hook that keeps this preflight out of the main analysis flow.

11. The repository includes a release/build packaging layer.

scripts/build-skill.sh builds the distributable dist/watch.skill bundle for claude.ai. .github/workflows/release.yml automates that build on tag push and attaches the artifact to releases. This is the only CI-style infrastructure in the repo.

12. Testing is focused on the pure logic, not the external tools.

scripts/tests/ covers frame-scene behavior, pacing, and report generation. That suggests the repo’s most important correctness boundaries are its budgeting heuristics and report structure, while the actual ffmpeg/yt-dlp/Whisper calls are treated as integration dependencies.

13. Overall data flow is linear with one optional branch.

Input video → download/probe → frame extraction → transcript acquisition → report assembly → optional Obsidian save/open → Claude reads media and finalizes response. The only major conditional branch is transcription fallback from captions to Whisper, and the optional vault ingest at the end.