How to Configure the Default Detail Mode Using .env in Claude-Video

Set the WATCH_DETAIL environment variable in ~/.config/watch/.env to override the built-in default of balanced with transcript, efficient, or token-burner.

The bradautomates/claude-video repository provides a video analysis framework that extracts frames using configurable detail strategies. Instead of passing --detail flags for every command, you can establish a persistent default through a local environment file, eliminating repetitive CLI arguments while customizing frame extraction behavior for your specific workflow.

Understanding Detail Modes in Claude-Video

The detail mode controls how aggressively the system samples frames from video content—balancing token usage against visual comprehension. According to skills/watch/scripts/config.py, the library recognizes four distinct extraction strategies defined in the DETAILS set:

• transcript – Processes audio only, skipping visual frame extraction entirely
• efficient – Minimal frame sampling for cost-conscious processing
• balanced – Scene-aware sampling at 2 FPS maximum with a 100-frame cap (default)
• token-burner – Maximum frame extraction for highest visual fidelity

The built-in default is hardcoded as DEFAULT_DETAIL = "balanced" at line 12 of skills/watch/scripts/config.py.

Locating the Configuration File

The configuration system loads key-value pairs from ~/.config/watch/.env using python-dotenv. This file location takes precedence over system-wide environment variables during the resolution chain documented in lines 52-57 of the config module.

Setting WATCH_DETAIL in .env

Creating the Configuration Directory

Create the directory structure if it does not exist, then open the environment file:

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

Valid Detail Mode Values

Add the WATCH_DETAIL variable to your .env file:

WATCH_DETAIL=efficient

Supported values must match the set defined in the source: transcript, efficient, balanced, or token-burner. Lines beginning with # are treated as comments:

WATCH_DETAIL=balanced   # default – scene-aware frames, 2 fps max, 100-frame cap

How the Configuration Resolution Works

As implemented in skills/watch/scripts/config.py, the resolution follows a strict priority order:

1. Environment Variable Check – The code first inspects the process environment for WATCH_DETAIL (lines 52-57)
2. .env File Loading – If absent from the environment, it loads from ~/.config/watch/.env via load_dotenv()
3. Validation – The value is checked against DETAILS = {"transcript", "efficient", "balanced", "token-burner"}; unknown values trigger fallback behavior
4. Default Fallback – Invalid or missing values resolve to DEFAULT_DETAIL = "balanced" (line 12)
5. API Exposure – The final string is exposed through config.get_config()["detail"] and consumed by watch.py using detail = args.detail or str(config["detail"])

Verifying Your Configuration

Confirm your environment setup using Python:

from skills.watch.scripts import config

cfg = config.get_config()
print("Effective detail mode:", cfg["detail"])

Run the CLI without the --detail flag to verify automatic application:

watch https://www.youtube.com/watch?v=example

The command executes as if you had explicitly passed --detail efficient (or whichever mode you configured).

Summary

• The default detail mode is balanced, defined as a constant in skills/watch/scripts/config.py at line 12
• Set WATCH_DETAIL in ~/.config/watch/.env to override the default permanently across sessions
• Valid options are strictly limited to: transcript, efficient, balanced, and token-burner
• Configuration resolution validates inputs and exposes the final value via config.get_config()["detail"]
• Explicit CLI flags (--detail) override .env settings for single-command exceptions

Frequently Asked Questions

What happens if I set an invalid detail mode in .env?

The validation logic in skills/watch/scripts/config.py checks the WATCH_DETAIL value against the supported DETAILS set. If the value is invalid or the variable is missing, the system falls back to the built-in default of balanced defined at line 12.

Can I override the .env default for a single command?

Yes. The CLI --detail flag takes precedence over environment variables. According to the implementation in watch.py, the resolution uses args.detail or str(config["detail"]), meaning explicit command-line arguments override .env configurations for that specific execution.

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

The constant DEFAULT_DETAIL = "balanced" is explicitly defined at line 12 of skills/watch/scripts/config.py. This value serves as the fallback when WATCH_DETAIL is unset, missing from the .env file, or contains an unsupported value.

Do I need to restart my terminal after editing .env?

No. The load_dotenv() function reads the .env file fresh each time the Python process initializes. Changes take effect immediately for new watch commands or Python sessions without requiring terminal restarts or shell configuration reloads.

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