How claude-video Cleans Up Working Directories After Video Processing

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, the script creates a uniquely prefixed directory to contain all processing artifacts:

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 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, the code iterates over matching glob patterns and unlinks each file:

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) builds a set of kept frame paths, then deletes the discarded candidates:

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) removes the redundant files:

# 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) clears existing cue_*.jpg files before extracting new cue frames:

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), claude-video prints a formatted reminder directing the user to delete the temporary folder:

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, 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 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 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.

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