How to Use Local Video Files with the /watch Command in Claude Video

Yes, you can feed local video files directly to the /watch slash-command in Claude Video by providing a file system path instead of a URL.

The bradautomates/claude-video repository supports both remote streams and offline content through its flexible input resolver. When you pass a local path to the /watch command, the system automatically detects it as a non-URL and routes it through a dedicated local-file handler, processing it through the same metadata extraction, frame sampling, and transcription pipeline used for online videos.

How Local File Detection Works

The /watch command distinguishes between remote URLs and local file paths using a systematic validation process defined in the download utility scripts.

Argument Parsing in watch.py

The entry point skills/watch/scripts/watch.py defines a positional source argument that accepts either a video URL or a local file path.

ap.add_argument("source", help="Video URL or local file path")

The script passes this value to a conditional check that determines whether to treat the input as a remote resource or a local file.

URL Detection Logic

Before fetching content, the system calls the is_url helper function located in skills/watch/scripts/download.py (lines 20-25). This utility checks if the provided string starts with http or https.

When is_url returns False, the code immediately branches to local-file resolution rather than attempting a network download.

Local File Resolution

For non-URL inputs, watch.py invokes download(args.source, work / "download"), which routes to the resolve_local function in skills/watch/scripts/download.py (lines 27-38).

This function validates the file path, issues a warning if the extension isn't a recognized video format, and returns a dictionary containing the absolute file location under the key video_path. The script then proceeds with frame extraction and optional transcription using this resolved path.

Usage Examples

You can invoke local video processing through both direct command-line usage and within Claude AI chat contexts.

Command Line Interface

When running the skill locally during development, provide the absolute or relative path to your video file:

watch /path/to/my-video.mp4

The tool supports standard container formats including .mp4, .mkv, and .webm.

Claude AI Chat Integration

Within a Claude conversation, use the slash-command syntax followed by your local file path:

/watch /home/user/videos/lecture.mkv

The skill generates a markdown report containing extracted frames and, if available, a transcript of the video content.

Processing Specific Time Ranges

Limit analysis to a specific segment by including --start and --end timestamps:

/watch /home/user/videos/lecture.mkv --start 01:23 --end 02:45

This processes only the specified 82-second segment, reducing processing time and focusing the output on relevant content.

Summary

• Local files are fully supported: The /watch command accepts file system paths in addition to HTTP/HTTPS URLs.
• Automatic detection: The is_url function in download.py distinguishes between remote and local sources, routing non-URLs to resolve_local.
• Unified processing pipeline: Once resolved, local videos undergo identical metadata extraction, frame sampling, and transcription as streamed content.
• Flexible input formats: Any readable video file (.mp4, .mkv, .webm, etc.) works with the same CLI and chat interfaces.

Frequently Asked Questions

Can I use network-mounted or external drive paths with the /watch command?

Yes. As long as the file system path is readable by the Python environment executing the skill, network-attached storage (NAS) paths and external drive mount points function identically to local disk paths. The resolve_local function only validates file existence and extension; it does not distinguish between physical and network storage.

What video formats are compatible with the local file resolver?

The resolver accepts any format with a standard video extension, including .mp4, .mkv, .webm, .mov, and .avi. While download.py warns about unrecognized extensions, the underlying processing relies on FFmpeg-compatible decoders, so most modern codecs are supported provided the extraction tools can parse them.

Does using a local file skip the transcription step?

No. Local files proceed through the complete pipeline defined in skills/watch/scripts/transcribe.py. If the video contains embedded subtitles or if Whisper is configured, the skill generates transcripts exactly as it would for a downloaded remote video. The transcription occurs after video_path is established, regardless of the source origin.

How does the skill handle spaces or special characters in file paths?

The argument parser passes the source value as a single string token. You should quote paths containing spaces when using the CLI: watch "/path/to/my file.mp4". In Claude chat interfaces, the path is typically passed as a single argument unit, though standard shell escaping rules apply if running the underlying Python script directly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}