# Cleanup Process After Claude Video Analysis: Complete Technical Guide

> Learn the technical cleanup process after Claude video analysis. This guide details how to remove temporary artifacts and keep your host filesystem pristine. Read now.

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

---

**The cleanup process after Claude video analysis removes every temporary artifact—including working directories, extracted frames, and intermediate JPEGs—to ensure the host filesystem remains pristine after the `/watch` skill completes.**

The `bradautomates/claude-video` repository implements a comprehensive cleanup process after Claude video analysis to prevent disk pollution. When the `/watch` skill finishes processing a video, it systematically deletes temporary working directories and orphaned image files created during download, frame extraction, and transcription. This article examines the exact mechanisms, source file locations, and code implementations that guarantee no stray files persist after analysis.

## Overview of the Cleanup Architecture

The cleanup operates across three distinct layers, each targeting specific temporary artifacts generated during video processing. According to the source code in `skills/watch/scripts/`, the pipeline ensures complete removal of transient data regardless of whether the analysis succeeds or fails.

The process handles:

- **Temporary working directories** created with `tempfile.mkdtemp(prefix="watch-")`
- **Intermediate frame files** (`frame_*.jpg`) extracted during preprocessing
- **Cue images** (`cue_*.jpg`) generated for transcript processing
- **Discarded JPEGs** removed during even-sampling frame reduction

## Step-by-Step Cleanup Process

### Temporary Working Directory Removal

The primary cleanup occurs in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which orchestrates the entire pipeline. The script creates a temporary directory at the start of processing:

```python
import tempfile, shutil
from pathlib import Path

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

```

Even if exceptions occur during download, frame extraction, or transcription, the cleanup block executes unconditionally at the end:

```python

# -----------------------------------------------------------------

# Clean‑up (executed even if an exception occurs)

shutil.rmtree(work, ignore_errors=True)

```

The `ignore_errors=True` parameter ensures the process completes successfully even if partial files remain locked or corrupted.

### Stale Frame and Cue Image Cleanup

Before extracting new frames, the system removes existing JPEG artifacts to prevent contamination between runs. In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), both the `extract()` and `extract_scene_candidates()` functions perform preemptive cleanup.

For standard frame extraction (lines 75-77):

```python
out_dir.mkdir(parents=True, exist_ok=True)
for existing in out_dir.glob("frame_*.jpg"):
    existing.unlink()          # delete old frames

```

For transcript cue processing in `extract_at_timestamps` (lines 44-46):

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

```

This pattern ensures that abandoned `frame_*.jpg` and `cue_*.jpg` files from previous interrupted runs do not accumulate on the filesystem.

### Even-Sampling Deletion of Excess Frames

When the engine caps the number of frames to meet API limits, the `_even_sample()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) deletes the JPEG files corresponding to dropped candidates. This occurs after selecting evenly-spaced frames but before final processing:

```python
def _even_sample(candidates: list[dict], n: int) -> list[dict]:
    """Pick n evenly‑spaced candidates (including first & last),
    delete the JPEGs we drop, and re‑index the survivors."""
    # … compute which candidates to keep …

    for c in candidates_to_drop:
        Path(c["path"]).unlink()   # delete the unwanted JPEG

    # … re‑index remaining frames …

```

This targeted deletion prevents storage bloat when processing long videos that generate hundreds of initial frame candidates.

## Key Implementation Files

The cleanup process spans multiple modules in the `skills/watch/scripts/` directory:

- **[`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)** – Orchestrates the pipeline and handles the temporary work directory cleanup via `shutil.rmtree()`
- **[`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)** – Implements frame extraction, removes stale JPEGs, and contains the `_even_sample()` cleanup logic
- **[`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py)** – Downloads video into the temporary work folder that gets deleted by [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)
- **[`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py)** – Processes audio within the temporary directory structure
- **[`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py)** – Handles API communication and cleans up temporary request files

## Summary

- **Temporary directories** created with the `watch-` prefix are unconditionally deleted via `shutil.rmtree()` in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)
- **Stale frame files** (`frame_*.jpg`) and **cue images** (`cue_*.jpg`) are removed before new extractions using `Path.unlink()` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- **Excess frames** from even-sampling are deleted during the `_even_sample()` operation to prevent accumulation of unused JPEGs
- **Error resilience** is built into all cleanup operations, ensuring execution even when processing fails midway

## Frequently Asked Questions

### What files does Claude-Video delete after analysis?

Claude-Video deletes three categories of temporary files: the entire working directory created with `tempfile.mkdtemp(prefix="watch-")`, all `frame_*.jpg` files extracted during video processing, and all `cue_*.jpg` images generated for transcript alignment. The system also removes specific JPEG files discarded during the even-sampling frame reduction process.

### Where is the cleanup logic implemented?

The primary cleanup logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) for directory removal and [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) for image file cleanup. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script handles the final `shutil.rmtree()` call, while [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) manages the removal of stale and excess JPEG files through `Path.unlink()` operations in `extract()`, `extract_scene_candidates()`, and `_even_sample()`.

### Does Claude-Video cleanup run if the analysis fails?

Yes. The cleanup process in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) executes unconditionally at the end of the processing block, wrapped in a try-finally pattern or equivalent logic that ensures `shutil.rmtree(work, ignore_errors=True)` runs even when exceptions occur during download, extraction, or transcription phases.

### How does the even-sampling cleanup work?

When video analysis generates more frames than the API allows, the `_even_sample()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) selects evenly-spaced candidates while physically deleting the unwanted ones. For each frame candidate dropped from the selection, the function calls `Path(c["path"]).unlink()` to remove the corresponding JPEG file from disk before re-indexing the remaining frames.