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

Set the WATCH_DETAIL key in ~/.config/watch/.env to one of the supported values (transcript, efficient, balanced, or token-burner) to establish a persistent default detail mode that applies to all Claude-Video runs unless overridden by an environment variable.

Claude-Video, the open-source video analysis tool from the bradautomates/claude-video repository, extracts frames from video content based on a configurable detail mode. While you can specify this parameter per-command, configuring the default in your user-level environment file ensures consistent behavior across all sessions without manual flags.

Configuration Precedence Hierarchy

Claude-Video resolves the detail parameter through a three-tier precedence chain defined in skills/watch/scripts/config.py. The get_config() function (lines 51-55) implements this hierarchy:

1. Shell environment variable WATCH_DETAIL (highest priority)
2. Configuration file entry WATCH_DETAIL in ~/.config/watch/.env (middle priority)
3. Hard-coded default balanced defined in DEFAULT_DETAIL (lines 12-14) (lowest priority)

If the environment variable is unset, the system falls back to the value in ~/.config/watch/.env. If that file is missing or the key is absent, the application defaults to balanced mode.

Setting Up the Configuration File

Create the Directory Structure

First, ensure the configuration directory exists:

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

Configure the Default Detail Mode

Edit ~/.config/watch/.env and add the WATCH_DETAIL entry:

# ~/.config/watch/.env

# Choose one of: transcript, efficient, balanced, token-burner

WATCH_DETAIL=efficient

The configuration parser (starting at line 27 in skills/watch/scripts/config.py) reads each non-comment line as KEY=VALUE pairs. Lines 9-11 specify the file path ~/.config/watch/.env as the user configuration source.

Valid Detail Mode Options

According to the validation logic in skills/watch/scripts/config.py (lines 14-15), Claude-Video accepts exactly four detail modes:

• transcript – Minimal frame extraction optimized for audio transcription workflows
• efficient – Reduced frame sampling for faster processing and lower token usage
• balanced – Moderate sampling suitable for general-purpose analysis (the DEFAULT_DETAIL value)
• token-burner – Maximum frame extraction for deep visual analysis

If you specify any other value, the system falls back to balanced at line 57 during the get_config() execution.

Verifying Your Configuration

Confirm the active setting by importing the configuration module directly:

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

# Output: efficient

This uses the same get_config() function called by the main entry point in skills/watch/scripts/watch.py, ensuring your test reflects actual runtime behavior.

Temporarily Overriding the Default

To bypass the config file for a single invocation without editing ~/.config/watch/.env, set the environment variable inline:

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

This shell-level assignment takes precedence over both the configuration file and the built-in default, allowing you to switch modes on a per-command basis while keeping your persistent default intact.

Summary

• Create ~/.config/watch/.env to store persistent defaults for the Claude-Video tool
• Set WATCH_DETAIL to one of: transcript, efficient, balanced, or token-burner
• The file is parsed by skills/watch/scripts/config.py during each get_config() call
• Environment variables override file settings; invalid values automatically fall back to balanced
• Verify active settings programmatically by importing from skills.watch.scripts

Frequently Asked Questions

What is the default detail mode if I don't configure anything?

If ~/.config/watch/.env does not exist and the WATCH_DETAIL environment variable is unset, Claude-Video defaults to balanced mode. This is hard-coded in the DEFAULT_DETAIL constant at lines 12-14 of skills/watch/scripts/config.py.

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

Yes. The system always checks for a shell environment variable first. If WATCH_DETAIL exists in your shell environment, it overrides the value from ~/.config/watch/.env. If only the file exists, that value is used. If neither exists, the hard-coded default applies.

Where does Claude-Video read the configuration from?

The configuration loader specifically checks for ~/.config/watch/.env as defined at lines 9-11 in skills/watch/scripts/config.py. This path is resolved relative to the user's home directory, and the file is parsed as a standard key-value environment file during the get_config() initialization.

What happens if I set an invalid detail mode in the config file?

If the value in ~/.config/watch/.env is not one of the four accepted options, Claude-Video silently falls back to balanced. This validation and fallback logic occurs at line 57 in skills/watch/scripts/config.py, ensuring the application never attempts to process video with an unrecognized detail setting.

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