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

> Learn to configure a custom output directory for Claude-Video watch operations using the --out-dir flag. Specify your own working directory easily.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 51‑53):

```python
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:

```python
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)

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

```

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

### Specify a Custom Output Directory

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

```

Paths are expanded and directories created as needed:

```bash

# 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`:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/download.py) receives `out_dir / "download"`
- [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/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:

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

```

## Key Source Files Reference

| File | Purpose | Relevant Lines |
|------|---------|----------------|
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) | Video/subtitle download; uses `out_dir / "download"` subdirectory | Called with resolved `work` path |
| [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/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.