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

> Learn how to set the default detail mode in Claude Video. Easily configure this setting using CLI flags, environment variables, or by modifying the constant in the config file.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-26

---

**The default detail mode in Claude Video is `balanced`, defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). Lines 12-14 define the constant:

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py), lines 49-50):

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py):

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py).
- Unit tests in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py) and [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.