# How claude-video Cleans Up Working Directories After Video Processing

> Discover how claude-video cleans working directories after video processing. Learn about proactive file-level cleanup and manual top-level directory deletion.

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

---

**The claude-video toolkit creates a temporary working directory for each processing run, performs proactive file-level cleanup during frame extraction using `Path.unlink()`, and prompts the user to manually delete the top-level directory after generating the final report.**

The `claude-video` repository provides a Python-based video processing pipeline that analyzes media content through frame extraction and scene detection. When processing videos via the `/watch` command, the tool generates isolated temporary workspaces to manage downloaded media, extracted JPEG frames, and intermediate assets. Understanding how claude-video handles working directory cleanup requires examining both its incremental file deletion strategy during processing and its final manual removal workflow.

## Temporary Working Directory Creation

### Directory Initialization

At the start of each run, `claude-video` initializes a dedicated workspace using Python’s `tempfile` module. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the script creates a uniquely prefixed directory to contain all processing artifacts:

```python
import tempfile
from pathlib import Path
import sys

work_dir = Path(tempfile.mkdtemp(prefix="watch-"))
print(f"[watch] working dir: {work_dir}", file=sys.stderr)

```

This directory—typically located in the system’s temporary folder with a `watch-xxxxxx` pattern—stores downloaded media files, extracted frame sequences (`frame_*.jpg`), cue images (`cue_*.jpg`), and any partial processing results.

## Proactive File Cleanup During Processing

Rather than accumulating all intermediate files until the end, `claude-video` performs targeted deletions throughout the pipeline. The [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) module contains multiple functions that invoke `Path.unlink()` to remove obsolete files immediately after they are no longer needed.

### Clearing Stale Frames Before Extraction

Before generating new frame extractions, the `extract`, `extract_scene_candidates`, and `extract_keyframes` functions remove any pre-existing `frame_*.jpg` files to prevent contamination from previous runs. According to lines 75-77 in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the code iterates over matching glob patterns and unlinks each file:

```python
for existing in out_dir.glob("frame_*.jpg"):
    existing.unlink()

```

This ensures that only freshly extracted frames remain in the working directory.

### Removing Discarded Frames During Sampling

When down-sampling candidate frames to meet token limits, the `_even_sample` function (lines 100-107 in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)) builds a set of kept frame paths, then deletes the discarded candidates:

```python
keep_paths = {sel["path"] for sel in selected}
for cand in candidates:
    if cand["path"] not in keep_paths:
        Path(cand["path"]).unlink()

```

### Deduplication Cleanup

After perceptual deduplication identifies near-duplicate frames, the `_dedupe_by_deltas` function (lines 100-105 in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)) removes the redundant files:

```python

# After determining which frames to drop

for drop_path in frames_to_remove:
    drop_path.unlink()

```

### Cue Frame Cleanup

Similarly, the `extract_at_timestamps` function (lines 44-47 in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)) clears existing `cue_*.jpg` files before extracting new cue frames:

```python
for existing in out_dir.glob("cue_*.jpg"):
    existing.unlink()

```

## Final Directory Removal Workflow

### User-Prompted Deletion

Unlike the file-level cleanup that happens automatically during processing, the removal of the top-level working directory requires manual intervention. At the conclusion of the script (lines 86-87 in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)), `claude-video` prints a formatted reminder directing the user to delete the temporary folder:

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

```

This design choice preserves the working directory after processing completes, allowing users to inspect intermediate files, debug extraction issues, or retrieve specific frames before manually removing the folder.

## Summary

- **claude-video** creates isolated temporary directories using `tempfile.mkdtemp(prefix="watch-")` for each video processing run.
- **Proactive cleanup** occurs throughout the pipeline via `Path.unlink()` calls in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), removing stale frames before extraction and deleting discarded frames during sampling and deduplication.
- **Manual removal** is required for the top-level working directory, with the script printing a reminder at lines 86-87 in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) prompting users to delete the folder when finished.
- **Cleanup patterns** target specific file types (`frame_*.jpg`, `cue_*.jpg`) to ensure only the final curated frame set persists in the workspace.

## Frequently Asked Questions

### Does claude-video automatically delete the working directory after processing?

No, claude-video does not automatically delete the working directory. While it removes intermediate files during processing using `Path.unlink()`, the top-level temporary directory persists after the run completes. The script prints a reminder message indicating the work directory path and instructing the user to delete it manually when done.

### Which functions in frames.py handle intermediate file cleanup?

The primary cleanup functions in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) include the extraction helpers (`extract`, `extract_scene_candidates`, `extract_keyframes`) at lines 75-77, `_even_sample` at lines 100-107, `_dedupe_by_deltas` at lines 100-105, and `extract_at_timestamps` at lines 44-47. Each uses `Path.unlink()` to remove specific file patterns immediately after they become obsolete.

### How does claude-video prevent stale frames from previous runs?

Before writing new frames, the extraction functions glob for existing files matching `frame_*.jpg` or `cue_*.jpg` patterns and unlink them. This pre-extraction cleanup ensures that the working directory contains only the current run’s extracted frames, preventing contamination from previously processed media or interrupted runs.

### What happens to frames that are dropped during sampling or deduplication?

Frames that are excluded during the `_even_sample` down-sampling process or filtered out by `_dedupe_by_deltas` are immediately deleted via `Path.unlink()`. The functions maintain sets of paths to keep, then iterate through candidate lists to remove any files not present in the keep set, ensuring efficient disk usage throughout the pipeline.