How to Set the Default Detail Mode in Claude Video Watch Configuration

To set the default detail mode in Claude Video, add WATCH_DETAIL=<mode> to ~/.config/watch/.env where <mode> is one of transcript, efficient, balanced, or token-burner.

The bradautomates/claude-video repository provides a watch skill that analyzes video content using different frame sampling strategies controlled by the detail mode. Configuring the default behavior through the user-level configuration file ensures consistent frame selection across all video processing sessions without requiring command-line flags.

Understanding the Configuration Precedence

Claude Video resolves the active detail mode through a strict hierarchy defined in skills/watch/scripts/config.py. The system checks three sources in descending order of priority:

1. Environment variable WATCH_DETAIL set in your shell session
2. Configuration file key WATCH_DETAIL located at ~/.config/watch/.env
3. Built-in fallback defined as DEFAULT_DETAIL = "balanced" (lines 12-14)

If the environment variable is unset, the system falls back to the config file value. If neither source provides a valid option, the system defaults to balanced mode.

Locating the Configuration File

The configuration helper reads user settings from ~/.config/watch/.env (lines 9-11). This file uses standard KEY=VALUE syntax, with each non-comment line parsed by the loading loop starting at line 27.

Create the directory and file if they do not exist:

mkdir -p ~/.config/watch
touch ~/.config/watch/.env

Setting the Default Detail Mode

To persistently change the default detail mode for all Claude Video invocations, edit ~/.config/watch/.env and specify your preferred mode.

# ~/.config/watch/.env

# Valid options: transcript, efficient, balanced, token-burner

WATCH_DETAIL=efficient

The get_config() function (lines 51-55) merges this value into the runtime configuration. Valid modes include:

• transcript: Audio-only analysis with no frame extraction
• efficient: Minimal frame sampling for faster processing
• balanced: Moderate frame sampling (default fallback)
• token-burner: Maximum frame extraction for detailed visual analysis

Validating the Configuration

If you supply an invalid value for WATCH_DETAIL, the system enforces the hard-coded default balanced (line 57).

Verify your active configuration using Python:

from skills.watch.scripts import config
print(config.get_config()["detail"])

# Output: "efficient" (or your configured value)

This imports the same configuration module used by skills/watch/scripts/watch.py, ensuring you see exactly what the watch command will use.

Temporarily Overriding the Default

Even with a default set in ~/.config/watch/.env, you can override the detail mode for individual commands using environment variables. This takes precedence over the config file without modifying your persistent settings.

# Override config file default for a single run

WATCH_DETAIL=token-burner claude-video /watch "https://youtu.be/example"

The watch entry point consumes this setting via config.get_config(), allowing seamless switching between modes without editing files.

Summary

• Primary method: Set WATCH_DETAIL=<mode> in ~/.config/watch/.env to change the default detail mode persistently
• Valid modes: Choose from transcript, efficient, balanced, or token-burner as defined in skills/watch/scripts/config.py
• Precedence: Environment variables override the config file, which overrides the built-in balanced default
• Validation: Invalid values automatically fall back to balanced mode
• Location: Configuration logic resides in skills/watch/scripts/config.py with the get_config() function merging all sources

Frequently Asked Questions

What are the valid detail modes in Claude Video?

The four accepted values for WATCH_DETAIL are transcript, efficient, balanced, and token-burner. These are validated against the allowed options at lines 14-15 of config.py. Each mode controls how many frames are extracted and analyzed from the input video, ranging from audio-only (transcript) to maximum visual detail (token-burner).

What happens if I set an invalid WATCH_DETAIL value?

If the configuration file or environment variable contains an unrecognized mode, the system falls back to the balanced setting. This validation occurs in skills/watch/scripts/config.py at line 57, ensuring that typos or incorrect values never break the video processing pipeline.

Can I use both the config file and environment variables together?

Yes. Claude Video uses a cascading configuration system where the environment variable WATCH_DETAIL takes highest precedence, followed by the ~/.config/watch/.env file entry, and finally the hard-coded default. You can maintain a baseline setting in the config file while using environment variables to override it temporarily for specific videos or workflows.

Where is the default detail mode defined in the source code?

The fallback default is defined as DEFAULT_DETAIL = "balanced" in skills/watch/scripts/config.py at lines 12-14. This constant is used by the get_config() function when neither the environment variable nor the config file provides a valid detail mode setting.

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