How Claude-Video Manages Working Directory Creation and Temporary File Cleanup

Working directory management in Claude-Video is handled by the watch skill, which creates a dedicated folder for each run; temporary files are never automatically deleted—users must remove the directory manually after the skill finishes.

The claude-video repository implements a deliberate, user-controlled approach to working directory management. Rather than hiding temporary files or performing automatic cleanup, the codebase prioritizes transparency and debugging flexibility. All intermediate artifacts—downloads, extracted frames, and transcription outputs—are written to a single root directory whose lifetime is entirely under the caller's control.

---

Working Directory Creation: Two Modes

The entry point watch.py implements two mutually exclusive strategies for establishing the working directory.

User-Specified Output Directory (--out-dir)

When the caller provides an explicit path via the --out-dir CLI flag, the script resolves the path, creates the directory if needed, and uses it for all subsequent operations. This mode is preferred for persistent artifacts, CI/CD pipelines, or when integrating with external orchestrators.

python -m skills.watch.scripts.watch https://youtu.be/example --out-dir ./my-report

Automatic Temporary Directory (Default Behavior)

If --out-dir is omitted, the script falls back to Python's tempfile.mkdtemp. In skills/watch/scripts/watch.py at line 86, the code creates a uniquely-named folder under the system temp area:

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

This generates paths such as /tmp/watch-abc123 on Linux or equivalent locations on macOS and Windows. The variable work is then passed to all downstream modules as the root for artifact storage.

---

Where Temporary Files Are Written

All modules in the watch skill write their outputs as subdirectories of the single work folder. This consolidated design means deleting the root directory removes every intermediate file in one operation.

Module	Output Subdirectory	Purpose
download.py	work/download	yt-dlp video and audio downloads
frames.py	work/frames	Extracted video frames as images
transcribe.py	work/ (varies)	VTT caption processing and output
whisper.py	work/ (varies)	Whisper transcription artifacts

Because no module writes outside work, there are no hidden temporary files scattered in system locations.

---

Cleanup Behavior: Intentionally Manual

The codebase does not delete the working directory automatically. After the final report is printed, watch.py outputs a explicit reminder:

_Work dir: `<work>` — delete when done._

This design decision serves several purposes:

• Debugging – Downstream hosts (Claude Code, Codex, Cursor, etc.) can inspect intermediate artifacts after a run fails or produces unexpected results
• Reproducibility – Users can rerun transcription or frame extraction without re-downloading source videos
• Orchestrator flexibility – External systems can implement their own retention policies, archival, or cleanup schedules

---

Practical Examples

Run with Automatic Temporary Directory

python -m skills.watch.scripts.watch https://youtu.be/example

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

# ... analysis report ...

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

Run with Persistent Output Directory

python -m skills.watch.scripts.watch https://youtu.be/example --out-dir ./reports/talk-2024

# [watch] working dir: /home/user/reports/talk-2024

# ... analysis report ...

# _Work dir: `/home/user/reports/talk-2024` — delete when done._

Manual Cleanup Commands

# Remove auto-generated temp directory

rm -rf /tmp/watch-abc123

# Remove user-specified directory

rm -rf ./reports/talk-2024

# Or use a wrapper script for automatic cleanup

WORKDIR=$(python -m skills.watch.scripts.watch https://youtu.be/example --out-dir /tmp/mytemp | grep "working dir:" | awk '{print $NF}')

# ... do work ...

rm -rf "$WORKDIR"

---

Source Implementation Details

The working directory logic is concentrated in skills/watch/scripts/watch.py, which serves as the entry point. Key implementation characteristics:

• Path resolution: Uses pathlib.Path for cross-platform compatibility
• Directory creation: Relies on tempfile.mkdtemp(prefix="watch-") for unique, collision-free names
• Propagation: The work Path object is passed explicitly to download_video(), extract_frames(), and other helper functions
• Final message: Printed unconditionally, regardless of whether the directory was user-supplied or auto-generated

As implemented in bradautomates/claude-video, this approach trades convenience for control—ensuring that no data is lost unexpectedly and that every artifact remains accessible for inspection.

---

Summary

• --out-dir flag lets users specify a persistent working directory; otherwise, tempfile.mkdtemp creates a temporary folder with a watch- prefix
• All artifacts are confined to subdirectories of the single work folder, with no external temporary files
• No automatic cleanup occurs; the script prints the working directory path and a manual deletion reminder
• Manual removal via rm -rf (or external orchestrator) is required to free disk space

---

Frequently Asked Questions

Why doesn't Claude-Video delete temporary files automatically?

The design prioritizes debugging and integration flexibility. By preserving all intermediate artifacts—downloads, frames, transcriptions—the skill allows downstream hosts and users to diagnose failures, rerun partial pipelines, or implement custom retention policies. Automatic deletion would prevent post-hoc analysis of failed runs.

How do I ensure temporary files are cleaned up when using Claude-Video programmatically?

Capture the working directory path from the script output, then wrap the call in a cleanup handler. For shell usage: WORKDIR=$(python -m skills.watch.scripts.watch URL | grep "working dir:" | awk '{print $NF}') && trap "rm -rf $WORKDIR" EXIT. For Python integration, parse the printed path and use shutil.rmtree() after processing.

What happens if I specify --out-dir but the directory already exists?

The script uses the existing directory and writes artifacts into it. No error is raised for pre-existing paths, allowing incremental updates or multiple runs to share a workspace. Users must ensure sufficient permissions and disk space in the target location.

Are there any hidden temporary files outside the working directory?

No. According to the source code in download.py, frames.py, transcribe.py, and whisper.py, all modules write exclusively within the work directory tree passed from watch.py. This guarantees that a single rm -rf <work> removes every artifact generated during the run.

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