How to Configure the Default Detail Mode Using `~/.config/watch/.env` in Claude-Video

Set the WATCH_DETAIL environment variable in ~/.config/watch/.env to control how many frames the watch skill extracts from videos, choosing from transcript, efficient, balanced, or token-burner.

The bradautomates/claude-video repository provides a watch skill that processes video content with adjustable visual detail levels. Rather than passing flags to every command, you can configure the default detail mode permanently by creating a environment file at ~/.config/watch/.env.

Understanding the Four Detail Modes

The watch skill uses a detail dial that determines frame extraction density. According to the source code in skills/watch/scripts/config.py, you can select one of four modes:

• transcript – Extracts no frames; returns only timestamped text transcripts.
• efficient – Fast key-frame extraction with an approximate 50-frame cap.
• balanced – Scene-aware extraction with an approximate 100-frame cap. This is the hard-coded default defined on line 12 of config.py.
• token-burner – Scene-aware extraction with no frame cap, providing maximum visual detail.

Locating the Configuration File

The tool reads persistent configuration from ~/.config/watch/.env using the python-dotenv package. This location follows the XDG Base Directory specification and applies globally to all watch skill invocations on your system.

If the directory does not exist, create it:

mkdir -p ~/.config/watch

Setting the Default Detail Mode

To change the default behavior, define the WATCH_DETAIL variable in your environment file.

Step 1: Create or Edit the Environment File

Open ~/.config/watch/.env in your preferred editor:

nano ~/.config/watch/.env

Step 2: Add the WATCH_DETAIL Variable

Choose your preferred mode and add it to the file:

# ~/.config/watch/.env

WATCH_DETAIL=efficient

Or for maximum detail:

# ~/.config/watch/.env

WATCH_DETAIL=token-burner

Save the file. The change takes effect immediately for the next watch skill execution.

How the Configuration Resolution Works

The precedence logic is implemented in skills/watch/scripts/config.py within the get_config() function (lines 37–53). The code checks three sources in order:

1. Environment variable (os.environ.get("WATCH_DETAIL")) – Highest priority, allowing temporary overrides.
2. File values (file_values.get("WATCH_DETAIL")) – Values loaded from ~/.config/watch/.env via load_dotenv.
3. Hard-coded default (DEFAULT_DETAIL) – Falls back to "balanced" if no other value is found.

This hierarchy means your .env file setting persists across sessions, but you can still override it temporarily using shell environment variables or command-line flags.

Verifying Your Configuration

You can confirm the active default by importing the configuration module directly:

from skills.watch.scripts import config

cfg = config.get_config()
print("Current default detail:", cfg["detail"])

If your .env file contains WATCH_DETAIL=efficient, the output shows:

Current default detail: efficient

Summary

• The default detail mode in bradautomates/claude-video is controlled by the WATCH_DETAIL environment variable.
• Create ~/.config/watch/.env and set WATCH_DETAIL to transcript, efficient, balanced, or token-burner.
• The resolution order is: shell environment > .env file > hard-coded "balanced" default (defined in skills/watch/scripts/config.py).
• Command-line flags take precedence over the .env file for one-off overrides.

Frequently Asked Questions

What happens if I don't set WATCH_DETAIL in the .env file?

If ~/.config/watch/.env does not exist or lacks the WATCH_DETAIL variable, the tool falls back to the hard-coded DEFAULT_DETAIL = "balanced" constant defined at line 12 of skills/watch/scripts/config.py.

Can I override the .env default for a single video analysis?

Yes. You can pass the --detail flag on the command line, which takes precedence over both the environment variable and the .env file. For example: watch https://youtu.be/example --detail token-burner.

What's the difference between efficient and token-burner modes?

efficient caps extraction at approximately 50 key frames for speed and lower token usage, while token-burner uses scene-aware detection with no frame limit, extracting every significant visual change regardless of cost or processing time.

Where is the configuration precedence defined in the source code?

The precedence logic appears in skills/watch/scripts/config.py at lines 37–53 inside the get_config() function, where the code explicitly checks os.environ, then file_values (populated by load_dotenv), then the DEFAULT_DETAIL fallback.

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