How to Set the Default Detail Mode in claude-video Using ~/.config/watch/.env

Add WATCH_DETAIL=<mode> to ~/.config/watch/.env to persist your preferred detail setting across all claude-video invocations without exporting environment variables in every shell session.

The claude-video project (available at bradautomates/claude-video) provides a flexible configuration system for controlling video frame extraction through "detail modes." Rather than passing flags on every command, you can persist your preferred setting by configuring the WATCH_DETAIL variable in a dedicated environment file.

Understanding the Configuration Precedence

Claude-video resolves the active detail mode through a three-tier fallback system defined in skills/watch/scripts/config.py. The hierarchy follows this priority order:

1. Shell environment variables - An exported WATCH_DETAIL takes highest precedence
2. User configuration file - The WATCH_DETAIL key in ~/.config/watch/.env (parsed at lines 9-11)
3. Hard-coded default - Falls back to balanced (defined in DEFAULT_DETAIL at lines 12-14)

When the configuration loader runs, it merges these sources in the get_config() function (lines 51-55), with later sources overriding earlier ones.

Setting WATCH_DETAIL in ~/.config/watch/.env

To establish a permanent default, create or edit the configuration file at ~/.config/watch/.env.

Supported Detail Modes

According to lines 14-15 of skills/watch/scripts/config.py, valid values include:

• transcript - Minimal frame extraction optimized for transcript-only analysis
• efficient - Reduced frame sampling for faster processing
• balanced - Default moderate sampling (defined in DEFAULT_DETAIL at line 12)
• token-burner - Maximum frame density for detailed visual analysis

Creating the Configuration File

Create the directory and file if they don't exist:

mkdir -p ~/.config/watch
echo "WATCH_DETAIL=efficient" > ~/.config/watch/.env

The parser (line 27 in config.py) reads each non-comment line as KEY=VALUE pairs. Lines beginning with # are ignored as comments.

Example configuration:

# ~/.config/watch/.env

# Options: transcript, efficient, balanced, token-burner

WATCH_DETAIL=efficient

Verifying Your Configuration

Inspect the active configuration through Python to confirm the file is loading correctly:

from skills.watch.scripts import config

cfg = config.get_config()
print(cfg["detail"])  # Outputs: "efficient"

If the file contains an invalid value, the system falls back to balanced (line 57), protecting against configuration errors.

Overriding Defaults Temporarily

Even with a persisted configuration, you can override the detail mode for single invocations by setting the shell environment variable:

# Overrides ~/.config/watch/.env for this command only

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

This temporary override takes precedence over the file-based configuration per the merging logic in get_config().

Summary

• Configuration file location: ~/.config/watch/.env
• Key variable: WATCH_DETAIL (validated against accepted modes in lines 14-15 of config.py)
• Precedence order: Shell environment > Config file > Default (balanced)
• Validation: Invalid values fall back to balanced at line 57 of skills/watch/scripts/config.py
• Syntax: Standard KEY=VALUE format with # for comments (parsed at line 27)

Frequently Asked Questions

What happens if I set an invalid detail mode in ~/.config/watch/.env?

If you specify a value not in the allowed set (transcript, efficient, balanced, token-burner), the configuration loader at line 57 of skills/watch/scripts/config.py automatically falls back to the balanced default. The application will run without errors, but will use the fallback setting instead of your invalid entry.

Can I use claude-video without creating the ~/.config/watch/.env file?

Yes. The configuration system is optional. If ~/.config/watch/.env does not exist, or if it exists but lacks a WATCH_DETAIL entry, claude-video defaults to balanced mode as defined by DEFAULT_DETAIL at lines 12-14 of config.py.

Does the WATCH_DETAIL environment variable override the config file?

Yes. The merging logic in get_config() (lines 51-55) prioritizes shell environment variables over file-based settings. If you export WATCH_DETAIL in your shell, it will supersede any value set in ~/.config/watch/.env for that session.

Where is the detail setting actually consumed in the codebase?

The entry point skills/watch/scripts/watch.py imports and calls config.get_config(), which returns a dictionary containing the resolved detail key. This value then controls frame extraction behavior throughout the video processing pipeline.

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