How Claude Video Manages and Cleans Up Its Working Directory

Claude Video creates working directories using either a user-specified --out-dir path or an auto-generated temporary folder with tempfile.mkdtemp(), then leaves cleanup entirely to the user with explicit guidance on when to delete.

The bradautomates/claude-video repository is a video analysis skill designed for AI coding environments. When processing video content, it needs a dedicated space for downloaded assets, extracted frames, and temporary audio files. Understanding how this working directory is managed—and why you're responsible for cleaning it up—is essential for running the tool effectively across different host environments.

Creating the Working Directory

The working directory logic lives in skills/watch/scripts/watch.py. When the watch command executes, it determines the workspace location through a simple conditional check.

Automatic Temporary Directory

If no output path is provided, Claude Video creates a temporary directory with a watch- prefix:

# watch.py – lines 83-88

if args.out_dir:
    work = Path(args.out_dir).expanduser().resolve()
else:
    work = Path(tempfile.mkdtemp(prefix="watch-"))
work.mkdir(parents=True, exist_ok=True)
print(f"[watch] working dir: {work}", file=sys.stderr)

This outputs the directory path to stderr so you always know where files are being stored, even when the main report goes to stdout.

User-Specified Directory

When you pass --out-dir, that path is expanded, resolved to absolute form, and used directly. This is useful for debugging, re-running analysis on the same assets, or integrating with external workflows that need predictable paths.

What Goes Into the Working Directory

Once established, the working directory holds three categories of intermediate files:

Subdirectory/File	Purpose	Source Module
work / "download"	Downloaded video and audio assets	download.py
work / "frames"	Frame images extracted via ffmpeg	frames.py
work / "audio.mp3"	Temporary audio file for Whisper transcription	whisper.py

These locations are hardcoded relative to the working directory root, making the file structure consistent regardless of how the workspace was created.

Cleanup Strategy: Explicit User Responsibility

Claude Video does not delete the working directory automatically. Instead, it prints a cleanup reminder at the end of every report:

# watch.py – lines 86-88 (end of script)

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

This design decision is deliberate. The codebase contains no shutil.rmtree calls, atexit handlers, or context managers that would auto-remove files. You retain full control over when and whether to delete the directory.

Why Auto-Cleanup Is Intentionally Absent

Two factors drive this manual cleanup approach:

• Cross-host compatibility — Claude Video runs in varied environments including Claude Code, Codex, Cursor, and standalone scripts. Some hosts may need to persist data for downstream processing, so automatic deletion could break external tooling.

• Transparency over convenience — Explicit guidance (_Work dir: ... — delete when done._) avoids hidden side-effects. You can inspect extracted frames, debug download issues, or reuse audio files without the tool silently removing evidence.

Practical Usage Examples

Run with automatic temporary directory

python3 skills/watch/scripts/watch.py "https://youtu.be/example" --detail balanced

# Standard error will show:

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

# ... (analysis report) ...

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

Run with persistent workspace for debugging

python3 skills/watch/scripts/watch.py "video.mp4" --out-dir ./my-workspace

# Output:

# [watch] working dir: /full/path/to/my-workspace

# ... (analysis report) ...

# _Work dir: `/full/path/to/my-workspace` — delete when done._

Manual cleanup after inspection

rm -r /tmp/watch-abc123      # automatic temp directory

# or

rm -r ./my-workspace         # user-specified directory

Key Source Files

Understanding the working directory flow requires familiarity with these modules in the bradautomates/claude-video repository:

• skills/watch/scripts/watch.py — Main orchestrator; creates directory, delegates to sub-modules
• skills/watch/scripts/download.py — Populates work/download/
• skills/watch/scripts/frames.py — Populates work/frames/
• skills/watch/scripts/whisper.py — Creates work/audio.mp3
• skills/watch/SKILL.md — Documents the entry point and working directory behavior

Summary

• Working directory creation uses tempfile.mkdtemp(prefix="watch-") by default, or --out-dir when specified
• Directory announcement goes to stderr so you always know the location
• File organization follows a predictable structure: download/, frames/, and audio.mp3
• No automatic deletion — you control cleanup timing via the printed reminder
• Design rationale prioritizes cross-host compatibility and user transparency over convenience

Frequently Asked Questions

Does Claude Video delete temporary files automatically?

No. Claude Video intentionally avoids automatic cleanup. According to the source code in watch.py, no shutil.rmtree or similar deletion calls exist. The tool prints a message indicating where files are stored and expects you to run rm -r when finished.

How do I specify a custom working directory?

Use the --out-dir argument when running the watch script. The path is expanded via Path.expanduser().resolve(), so ~ and relative paths work correctly. This is useful for debugging or when you need predictable paths for external tooling.

What files are stored in the working directory?

The working directory contains three items: a download/ subdirectory for video assets, a frames/ subdirectory for extracted images, and audio.mp3 for Whisper transcription input. These are created by download.py, frames.py, and whisper.py respectively.

Why design for manual cleanup instead of automatic deletion?

The repository targets multiple AI coding hosts (Claude Code, Codex, Cursor) where automatic deletion could interfere with host-specific workflows. Explicit user guidance keeps behavior transparent and prevents data loss in environments that expect persistent intermediate files.

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