How to Configure a Custom Output Directory for Watch Operations in Claude‑Video

Use the --out-dir command‑line flag when invoking the watch skill to override the default temporary folder and specify your own working directory.

The watch skill in the bradautomates/claude-video repository processes videos through multiple stages—downloading, frame extraction, subtitle generation, and optional audio transcription. Understanding how to customize the output directory for these operations lets you control where intermediate files are stored, persist results across runs, and integrate the tool into automated workflows.

Understanding the Default Behavior

By default, watch creates a temporary working directory using Python's tempfile.mkdtemp(). This directory serves as the parent for all sub‑directories:

• download/ — video files and metadata
• frames/ — extracted frame images
• Temporary audio files (when Whisper fallback is used)

The temporary directory is automatically cleaned up, which makes the default unsuitable when you need to inspect or reuse the generated assets.

Using the --out-dir Flag

The --out-dir argument is the sole mechanism for redirecting output. As implemented in skills/watch/scripts/watch.py, the flag accepts an absolute or tilde‑expanded path, creates the directory if it doesn't exist, and uses it as the base for all operations.

Argument Definition

In skills/watch/scripts/watch.py (lines 51‑53):

parser.add_argument(
    "--out-dir",
    type=Path,
    help="Directory to store downloaded video, frames, and other outputs",
)

Working Directory Selection Logic

Lines 83‑87 handle the path resolution:

if args.out_dir:
    work_dir = args.out_dir.expanduser().resolve()
    work_dir.mkdir(parents=True, exist_ok=True)
else:
    work_dir = Path(tempfile.mkdtemp(prefix="claude_video_"))

Command‑Line Examples

Basic Usage (Default Temporary Directory)

watch "https://youtu.be/example"

All files are written to a system temporary folder and removed automatically.

Specify a Custom Output Directory

watch "https://youtu.be/example" --out-dir ~/my-watch-output

Paths are expanded and directories created as needed:

# Absolute path

watch "https://youtu.be/example" --out-dir /var/lib/video-processing

# Relative path (resolved from current working directory)

watch "https://youtu.be/example" --out-dir ./outputs/batch-001

Programmatic Invocation

When wrapping watch in automation scripts, pass --out-dir through subprocess:

import subprocess
from pathlib import Path

video_url = "https://youtu.be/example"
output_path = Path("~/my-watch-output").expanduser()

subprocess.run([
    "python3",
    "-m",
    "skills.watch.scripts.watch",
    video_url,
    "--out-dir",
    str(output_path),
])

This pattern is compatible with Agent Skills hosts that invoke the skill via slash commands—the flag works identically whether run directly from the shell or through an agent interface.

Directory Structure After Processing

With a custom --out-dir, the skill organizes outputs as follows:

my-watch-output/
├── download/
│   ├── video.mp4
│   └── video.info.json
├── frames/
│   ├── frame_0001.jpg
│   ├── frame_0002.jpg
│   └── ...
└── audio.mp3          # Present only if Whisper transcription is triggered

Each sub‑directory is created under the supplied base path:

• download.py receives out_dir / "download"
• frames.py receives out_dir / "frames"

Environment Variables and Alternatives

There is no environment variable support for configuring the output directory. The --out-dir flag remains the only supported mechanism. This design choice keeps configuration explicit and avoids side effects from shell environments.

If you need environment‑based configuration, wrap the invocation in a shell script or wrapper that reads your variable and supplies the flag:

#!/bin/bash
watch "$1" --out-dir "${CLD_VIDEO_OUTPUT:-./default-output}"

Key Source Files Reference

File	Purpose	Relevant Lines
skills/watch/scripts/watch.py	Entry point; parses --out-dir and initializes working directory	51‑53 (argument), 83‑87 (resolution logic)
skills/watch/scripts/download.py	Video/subtitle download; uses out_dir / "download" subdirectory	Called with resolved work path
skills/watch/scripts/frames.py	Frame extraction; uses out_dir / "frames" subdirectory	Receives same base path

Summary

• Primary method: Pass --out-dir <path> when invoking watch
• Path handling: Supports tilde expansion (~) and automatic directory creation
• No alternatives: Environment variables are not supported
• Consistent behavior: Works for command‑line use and Agent Skills invocation
• Structured output: Custom directory receives download/, frames/, and auxiliary files

Frequently Asked Questions

What happens if the specified directory already exists?

The skill proceeds without error. mkdir(parents=True, exist_ok=True) ensures the directory and any required parent directories are created if missing, or left untouched if present. Existing files with matching names will be overwritten by subsequent operations.

Can I use relative paths with --out-dir?

Yes. Relative paths are resolved against the current working directory at runtime. For predictable behavior in scripts, prefer absolute paths or explicit tilde expansion.

Does --out-dir affect where the final Claude artifact is saved?

No. The --out-dir controls intermediate working files only. Final artifacts delivered to the conversation depend on the host application's configuration, not the skill's working directory.

Is there a way to persist outputs without specifying --out-dir every time?

Not natively. The skill intentionally avoids configuration files or environment variables for output location. Create shell aliases, wrapper scripts, or host‑specific presets to streamline repeated invocations with consistent output directories.

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