Cleanup Process After Claude Video Analysis: Complete Technical Guide

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, which orchestrates the entire pipeline. The script creates a temporary directory at the start of processing:

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:

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

# 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, both the extract() and extract_scene_candidates() functions perform preemptive cleanup.

For standard frame extraction (lines 75-77):

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):

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 deletes the JPEG files corresponding to dropped candidates. This occurs after selecting evenly-spaced frames but before final processing:

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 – Orchestrates the pipeline and handles the temporary work directory cleanup via shutil.rmtree()
• frames.py – Implements frame extraction, removes stale JPEGs, and contains the _even_sample() cleanup logic
• download.py – Downloads video into the temporary work folder that gets deleted by watch.py
• transcribe.py – Processes audio within the temporary directory structure
• 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
• Stale frame files (frame_*.jpg) and cue images (cue_*.jpg) are removed before new extractions using Path.unlink() in 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 for directory removal and skills/watch/scripts/frames.py for image file cleanup. The watch.py script handles the final shutil.rmtree() call, while 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}