How the `~/.config/watch/.env` Configuration File Works in Claude-Video

The ~/.config/watch/.env file stores user settings for the /watch command, parsed by config.py to provide persistent defaults for frame extraction behavior while allowing overrides via environment variables or CLI flags.

The bradautomates/claude-video repository uses a local dotenv file to manage user preferences for video analysis. Located at $HOME/.config/watch/.env, this configuration file controls how many frames Claude extracts from videos based on the WATCH_DETAIL setting.

Configuration File Location and Structure

Claude-Video defines its configuration paths as constants in skills/watch/scripts/config.py.

Default Paths

The module constructs the configuration directory and file paths using Python's pathlib:

CONFIG_DIR = Path.home() / ".config" / "watch"
CONFIG_FILE = CONFIG_DIR / ".env"

These definitions appear at lines 9–11 of config.py. If the directory does not exist, the application handles its creation as needed when writing or reading the configuration.

Parsing the Dotenv File

The configuration parser handles standard dotenv syntax while preserving special characters in values.

The read_env_file Function

Located at lines 17–45 of skills/watch/scripts/config.py, the read_env_file function processes the .env file with specific parsing rules:

• Splits content into individual lines and skips blank entries

• Strips surrounding quotes from quoted values (both single and double)

• Removes inline comments (# comment) only from unquoted values, preserving # characters inside quoted strings such as API keys

• Extracts KEY=VALUE pairs into a dictionary

This implementation ensures that values like GROQ_API_KEY="sk-xxx#123" retain the hash character, while unquoted values like WATCH_DETAIL=efficient # quick mode have the comment stripped.

Runtime Configuration with get_config

The get_config function at lines 48–62 builds the final configuration dictionary by merging file-based settings with system environment variables.

WATCH_DETAIL Variable and Defaults

The WATCH_DETAIL setting controls frame extraction behavior and supports four valid values:

Detail Level	Frame Behavior
efficient	Caps at 50 frames
balanced	Caps at 100 frames
token-burner	Unlimited frames (no cap)
transcript	No frames extracted (audio-only)

The function checks for WATCH_DETAIL in the following precedence:

1. Real OS environment variables (highest priority among persistent settings)
2. Keys defined in ~/.config/watch/.env
3. Built-in default of "balanced" (lowest priority)

Invalid values automatically normalize back to "balanced".

Frame Cap Mapping

The frame_cap dictionary at lines 65–74 maps detail levels to integer limits:

frame_cap = {
    "efficient": 50,
    "balanced": 100,
    "token-burner": float("inf"),
    "transcript": 0
}

The get_config function returns a dictionary containing the resolved detail value and the absolute path to config_file, enabling other modules to verify which configuration source is active.

Overriding Configuration Values

The /watch entry point in skills/watch/scripts/watch.py (line 71) calls get_config() and merges the result with command-line arguments:

config = get_config()
detail = args.detail or str(config["detail"])

This merge strategy allows temporary overrides without modifying the configuration file. You can set persistent defaults in the .env file, override them via environment variables for a session, or use --detail flags for single-command adjustments.

Configuration Precedence and Overrides

Claude-Video applies settings through a strict hierarchy where higher levels override lower ones:

1. CLI arguments (--detail token-burner) – Immediate, single-use override
2. OS environment variables (export WATCH_DETAIL=efficient) – Session-level override
3. Dotenv file (~/.config/watch/.env) – Persistent user defaults
4. Hardcoded defaults – Fallback when no user configuration exists

For example, to temporarily analyze a video with maximum detail extraction while keeping balanced as your default:

watch https://example.com/video.mp4 --detail token-burner

Or to set a session-wide efficient mode:

export WATCH_DETAIL=efficient
watch https://example.com/video.mp4

Summary

• The ~/.config/watch/.env file stores persistent configuration for the /watch command in bradautomates/claude-video
• skills/watch/scripts/config.py provides read_env_file for parsing and get_config for resolving configuration values
• WATCH_DETAIL accepts efficient, balanced, token-burner, or transcript, defaulting to balanced when invalid or unspecified
• The frame_cap dictionary maps detail levels to frame limits (50, 100, unlimited, or zero)
• Configuration precedence follows: CLI flags > OS environment variables > .env file > built-in defaults

Frequently Asked Questions

Where is the claude-video configuration file stored?

The configuration file is located at $HOME/.config/watch/.env on Unix-like systems. The path is constructed in skills/watch/scripts/config.py using Path.home() / ".config" / "watch" / ".env", ensuring it resides in the user's home directory under the standard XDG configuration path.

What values can I set for WATCH_DETAIL?

Valid WATCH_DETAIL values include efficient (50 frames), balanced (100 frames), token-burner (unlimited frames), and transcript (zero frames, audio-only). Any other value automatically normalizes to balanced. These mappings are defined in the frame_cap dictionary at lines 65–74 of config.py.

Can I use environment variables instead of the .env file?

Yes. Real OS environment variables take precedence over the .env file but yield to CLI flags. You can export WATCH_DETAIL=efficient in your shell session to override the file-based setting without modifying ~/.config/watch/.env.

How do I override the detail level for a single command?

Pass the --detail flag to the watch command. For example, watch https://example.com/video.mp4 --detail token-burner temporarily uses unlimited frame extraction regardless of your .env file or environment variable settings. This override logic is implemented in skills/watch/scripts/watch.py at line 71.

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