How to Set the Default Detail Mode in Claude Video: Configuration Guide

The default detail mode in Claude Video is balanced, defined in skills/watch/scripts/config.py, and you can override it via the --detail CLI flag, the WATCH_DETAIL environment variable, or by modifying the DEFAULT_DETAIL constant.

Claude Video uses a configurable detail setting to control how many frames are extracted from video content. According to the bradautomates/claude-video source code, this setting determines the visual analysis depth, with the default value hard-coded in the configuration module and multiple override mechanisms available.

Where the Default Detail Mode Is Defined

The canonical default resides in the configuration module at skills/watch/scripts/config.py. Lines 12-14 define the constant:

# skills/watch/scripts/config.py (lines 12-14)

DEFAULT_DETAIL = "balanced"

This string value acts as the fallback when no other configuration is provided.

How the Detail Mode Is Selected at Runtime

When you run the watch command, the system resolves the detail mode through a specific precedence chain. If the --detail argument is absent from the command line, the code checks the config dictionary for a "detail" key. If that key is missing or contains an invalid value, the system falls back to DEFAULT_DETAIL.

This logic appears in skills/watch/scripts/config.py around lines 54-57, where the configuration dictionary is validated and merged with defaults.

Supported Detail Modes and Frame Selection

Claude Video supports four distinct detail modes, each triggering a different frame-selection engine in skills/watch/scripts/watch.py (lines 72-73 and 204-209):

• efficient – Uses a key-frame extraction engine that minimizes token usage by sampling only significant frame changes.
• balanced – The default mode employing a scene-aware engine that balances comprehensiveness with token economy.
• token-burner – Extracts maximum frames for deep visual analysis, consuming the most API tokens.
• transcript – Focuses on audio transcription rather than visual frame analysis.

Three Methods to Configure the Default Detail Mode

You can customize the default behavior without editing source code, or permanently change the hard-coded default.

1. Use the --detail Flag for One-Off Changes

Override the default for a single execution by passing the --detail argument to the CLI:

claude-video watch https://youtu.be/example --detail token-burner

2. Set the WATCH_DETAIL Environment Variable

To persist a custom default across sessions without modifying code, export the WATCH_DETAIL environment variable. The test suite confirms this variable is read before the configuration loads (as seen in tests/test_config.py, lines 49-50):

# Linux/macOS

export WATCH_DETAIL=efficient

# Windows PowerShell

$env:WATCH_DETAIL = "efficient"

# Windows CMD

set WATCH_DETAIL=efficient

3. Modify the DEFAULT_DETAIL Constant

For a permanent change to the package default, edit the constant in skills/watch/scripts/config.py:

# skills/watch/scripts/config.py

DEFAULT_DETAIL = "efficient"  # Changed from "balanced"

This change affects all future runs where neither the environment variable nor CLI argument is specified.

Summary

• The default detail mode in Claude Video is "balanced", defined as DEFAULT_DETAIL in skills/watch/scripts/config.py.
• Configuration precedence follows: CLI argument → WATCH_DETAIL environment variable → config["detail"] → DEFAULT_DETAIL constant.
• Four modes are available: efficient, balanced, token-burner, and transcript, each using different frame-selection engines in watch.py.
• Unit tests in tests/test_config.py and tests/test_watch.py validate the default value and override behavior.

Frequently Asked Questions

What is the default detail mode in Claude Video?

The default detail mode is "balanced". This value is hard-coded as the DEFAULT_DETAIL constant in skills/watch/scripts/config.py and is used when no --detail argument is provided and the WATCH_DETAIL environment variable is unset.

How do I permanently change the default detail mode without typing flags every time?

Set the WATCH_DETAIL environment variable in your shell profile (e.g., .bashrc or .zshrc) to your preferred mode. Alternatively, modify the DEFAULT_DETAIL constant in skills/watch/scripts/config.py to change the package-level default.

What are the differences between the detail modes?

According to the source code in skills/watch/scripts/watch.py, efficient uses a key-frame engine for minimal token usage, balanced uses a scene-aware engine for moderate analysis, token-burner maximizes frame extraction for detailed visual analysis, and transcript prioritizes audio over visual content.

Where is the detail mode configuration validated?

Validation occurs in skills/watch/scripts/config.py (lines 54-57), where the code checks the config dictionary for a valid "detail" entry and falls back to DEFAULT_DETAIL if the entry is missing or invalid.

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