# How Claude Video Manages and Cleans Up Its Working Directory

> Learn how Claude Video manages and cleans its working directory. Discover its use of user-specified or temporary folders and understand your cleanup responsibilities.

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

---

**Claude Video creates working directories using either a user-specified `--out-dir` path or an auto-generated temporary folder with `tempfile.mkdtemp()`, then leaves cleanup entirely to the user with explicit guidance on when to delete.**

The `bradautomates/claude-video` repository is a video analysis skill designed for AI coding environments. When processing video content, it needs a dedicated space for downloaded assets, extracted frames, and temporary audio files. Understanding how this working directory is managed—and why you're responsible for cleaning it up—is essential for running the tool effectively across different host environments.

## Creating the Working Directory

The working directory logic lives in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). When the `watch` command executes, it determines the workspace location through a simple conditional check.

### Automatic Temporary Directory

If no output path is provided, Claude Video creates a temporary directory with a `watch-` prefix:

```python

# watch.py – lines 83-88

if args.out_dir:
    work = Path(args.out_dir).expanduser().resolve()
else:
    work = Path(tempfile.mkdtemp(prefix="watch-"))
work.mkdir(parents=True, exist_ok=True)
print(f"[watch] working dir: {work}", file=sys.stderr)

```

This outputs the directory path to **stderr** so you always know where files are being stored, even when the main report goes to **stdout**.

### User-Specified Directory

When you pass `--out-dir`, that path is expanded, resolved to absolute form, and used directly. This is useful for debugging, re-running analysis on the same assets, or integrating with external workflows that need predictable paths.

## What Goes Into the Working Directory

Once established, the working directory holds three categories of intermediate files:

| Subdirectory/File | Purpose | Source Module |
|---|---|---|
| `work / "download"` | Downloaded video and audio assets | [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) |
| `work / "frames"` | Frame images extracted via ffmpeg | [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) |
| `work / "audio.mp3"` | Temporary audio file for Whisper transcription | [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) |

These locations are hardcoded relative to the working directory root, making the file structure consistent regardless of how the workspace was created.

## Cleanup Strategy: Explicit User Responsibility

Claude Video **does not delete** the working directory automatically. Instead, it prints a cleanup reminder at the end of every report:

```python

# watch.py – lines 86-88 (end of script)

print("---")
print(f"_Work dir: `{work}` — delete when done._")

```

This design decision is deliberate. The codebase contains no `shutil.rmtree` calls, `atexit` handlers, or context managers that would auto-remove files. You retain full control over when and whether to delete the directory.

## Why Auto-Cleanup Is Intentionally Absent

Two factors drive this manual cleanup approach:

- **Cross-host compatibility** — Claude Video runs in varied environments including Claude Code, Codex, Cursor, and standalone scripts. Some hosts may need to persist data for downstream processing, so automatic deletion could break external tooling.

- **Transparency over convenience** — Explicit guidance (`_Work dir: ... — delete when done._`) avoids hidden side-effects. You can inspect extracted frames, debug download issues, or reuse audio files without the tool silently removing evidence.

## Practical Usage Examples

### Run with automatic temporary directory

```bash
python3 skills/watch/scripts/watch.py "https://youtu.be/example" --detail balanced

# Standard error will show:

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

# ... (analysis report) ...

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

```

### Run with persistent workspace for debugging

```bash
python3 skills/watch/scripts/watch.py "video.mp4" --out-dir ./my-workspace

# Output:

# [watch] working dir: /full/path/to/my-workspace

# ... (analysis report) ...

# _Work dir: `/full/path/to/my-workspace` — delete when done._

```

### Manual cleanup after inspection

```bash
rm -r /tmp/watch-abc123      # automatic temp directory

# or

rm -r ./my-workspace         # user-specified directory

```

## Key Source Files

Understanding the working directory flow requires familiarity with these modules in the `bradautomates/claude-video` repository:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)** — Main orchestrator; creates directory, delegates to sub-modules
- **[`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py)** — Populates `work/download/`
- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)** — Populates `work/frames/`
- **[`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)** — Creates `work/audio.mp3`
- **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)** — Documents the entry point and working directory behavior

## Summary

- **Working directory creation** uses `tempfile.mkdtemp(prefix="watch-")` by default, or `--out-dir` when specified
- **Directory announcement** goes to stderr so you always know the location
- **File organization** follows a predictable structure: `download/`, `frames/`, and `audio.mp3`
- **No automatic deletion** — you control cleanup timing via the printed reminder
- **Design rationale** prioritizes cross-host compatibility and user transparency over convenience

## Frequently Asked Questions

### Does Claude Video delete temporary files automatically?

No. Claude Video intentionally avoids automatic cleanup. According to the source code in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), no `shutil.rmtree` or similar deletion calls exist. The tool prints a message indicating where files are stored and expects you to run `rm -r` when finished.

### How do I specify a custom working directory?

Use the `--out-dir` argument when running the watch script. The path is expanded via `Path.expanduser().resolve()`, so `~` and relative paths work correctly. This is useful for debugging or when you need predictable paths for external tooling.

### What files are stored in the working directory?

The working directory contains three items: a `download/` subdirectory for video assets, a `frames/` subdirectory for extracted images, and `audio.mp3` for Whisper transcription input. These are created by [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), and [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) respectively.

### Why design for manual cleanup instead of automatic deletion?

The repository targets multiple AI coding hosts (Claude Code, Codex, Cursor) where automatic deletion could interfere with host-specific workflows. Explicit user guidance keeps behavior transparent and prevents data loss in environments that expect persistent intermediate files.