# How Claude-Video Manages Working Directory Creation and Temporary File Cleanup

> Discover how Claude-Video's watch skill manages working directory creation. Learn that temporary files are not automatically deleted and require manual cleanup after use.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-08-03

---

**Working directory management in Claude-Video is handled by the `watch` skill, which creates a dedicated folder for each run; temporary files are never automatically deleted—users must remove the directory manually after the skill finishes.**

The **claude-video** repository implements a deliberate, user-controlled approach to working directory management. Rather than hiding temporary files or performing automatic cleanup, the codebase prioritizes transparency and debugging flexibility. All intermediate artifacts—downloads, extracted frames, and transcription outputs—are written to a single root directory whose lifetime is entirely under the caller's control.

---

## Working Directory Creation: Two Modes

The entry point [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) implements two mutually exclusive strategies for establishing the working directory.

### User-Specified Output Directory (`--out-dir`)

When the caller provides an explicit path via the `--out-dir` CLI flag, the script resolves the path, creates the directory if needed, and uses it for all subsequent operations. This mode is preferred for persistent artifacts, CI/CD pipelines, or when integrating with external orchestrators.

```bash
python -m skills.watch.scripts.watch https://youtu.be/example --out-dir ./my-report

```

### Automatic Temporary Directory (Default Behavior)

If `--out-dir` is omitted, the script falls back to Python's `tempfile.mkdtemp`. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at line 86, the code creates a uniquely-named folder under the system temp area:

```python
work = Path(tempfile.mkdtemp(prefix="watch-"))

```

This generates paths such as `/tmp/watch-abc123` on Linux or equivalent locations on macOS and Windows. The variable `work` is then passed to all downstream modules as the root for artifact storage.

---

## Where Temporary Files Are Written

All modules in the `watch` skill write their outputs as subdirectories of the single `work` folder. This consolidated design means **deleting the root directory removes every intermediate file in one operation**.

| Module | Output Subdirectory | Purpose |
|--------|---------------------|---------|
| [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) | `work/download` | yt-dlp video and audio downloads |
| [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) | `work/frames` | Extracted video frames as images |
| [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) | `work/` (varies) | VTT caption processing and output |
| [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) | `work/` (varies) | Whisper transcription artifacts |

Because no module writes outside `work`, there are no hidden temporary files scattered in system locations.

---

## Cleanup Behavior: Intentionally Manual

The codebase **does not delete the working directory automatically**. After the final report is printed, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) outputs a explicit reminder:

```

_Work dir: `<work>` — delete when done._

```

This design decision serves several purposes:

- **Debugging** – Downstream hosts (Claude Code, Codex, Cursor, etc.) can inspect intermediate artifacts after a run fails or produces unexpected results
- **Reproducibility** – Users can rerun transcription or frame extraction without re-downloading source videos
- **Orchestrator flexibility** – External systems can implement their own retention policies, archival, or cleanup schedules

---

## Practical Examples

### Run with Automatic Temporary Directory

```bash
python -m skills.watch.scripts.watch https://youtu.be/example

# [watch] working dir: /tmp/watch-abc123

# ... analysis report ...

# _Work dir: `/tmp/watch-abc123` — delete when done._

```

### Run with Persistent Output Directory

```bash
python -m skills.watch.scripts.watch https://youtu.be/example --out-dir ./reports/talk-2024

# [watch] working dir: /home/user/reports/talk-2024

# ... analysis report ...

# _Work dir: `/home/user/reports/talk-2024` — delete when done._

```

### Manual Cleanup Commands

```bash

# Remove auto-generated temp directory

rm -rf /tmp/watch-abc123

# Remove user-specified directory

rm -rf ./reports/talk-2024

# Or use a wrapper script for automatic cleanup

WORKDIR=$(python -m skills.watch.scripts.watch https://youtu.be/example --out-dir /tmp/mytemp | grep "working dir:" | awk '{print $NF}')

# ... do work ...

rm -rf "$WORKDIR"

```

---

## Source Implementation Details

The working directory logic is concentrated in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which serves as the entry point. Key implementation characteristics:

- **Path resolution**: Uses `pathlib.Path` for cross-platform compatibility
- **Directory creation**: Relies on `tempfile.mkdtemp(prefix="watch-")` for unique, collision-free names
- **Propagation**: The `work` Path object is passed explicitly to `download_video()`, `extract_frames()`, and other helper functions
- **Final message**: Printed unconditionally, regardless of whether the directory was user-supplied or auto-generated

As implemented in bradautomates/claude-video, this approach trades convenience for control—ensuring that no data is lost unexpectedly and that every artifact remains accessible for inspection.

---

## Summary

- **`--out-dir` flag** lets users specify a persistent working directory; otherwise, `tempfile.mkdtemp` creates a temporary folder with a `watch-` prefix
- **All artifacts** are confined to subdirectories of the single `work` folder, with no external temporary files
- **No automatic cleanup** occurs; the script prints the working directory path and a manual deletion reminder
- **Manual removal** via `rm -rf` (or external orchestrator) is required to free disk space

---

## Frequently Asked Questions

### Why doesn't Claude-Video delete temporary files automatically?

The design prioritizes debugging and integration flexibility. By preserving all intermediate artifacts—downloads, frames, transcriptions—the skill allows downstream hosts and users to diagnose failures, rerun partial pipelines, or implement custom retention policies. Automatic deletion would prevent post-hoc analysis of failed runs.

### How do I ensure temporary files are cleaned up when using Claude-Video programmatically?

Capture the working directory path from the script output, then wrap the call in a cleanup handler. For shell usage: `WORKDIR=$(python -m skills.watch.scripts.watch URL | grep "working dir:" | awk '{print $NF}') && trap "rm -rf $WORKDIR" EXIT`. For Python integration, parse the printed path and use `shutil.rmtree()` after processing.

### What happens if I specify `--out-dir` but the directory already exists?

The script uses the existing directory and writes artifacts into it. No error is raised for pre-existing paths, allowing incremental updates or multiple runs to share a workspace. Users must ensure sufficient permissions and disk space in the target location.

### Are there any hidden temporary files outside the working directory?

No. According to the source code in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py), and [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py), all modules write exclusively within the `work` directory tree passed from [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py). This guarantees that a single `rm -rf <work>` removes every artifact generated during the run.