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

> Configure Claude-Video default detail mode by setting WATCH_DETAIL in ~/.config/watch/.env. Choose transcript, efficient, balanced, or token-burner for persistent settings.

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

---

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

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

```

### Configure the Default Detail Mode

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

```text

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

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

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), ensuring the application never attempts to process video with an unrecognized detail setting.