# How to Configure the Default Detail Mode Using .env in Claude-Video

> Configure the default detail mode in Claude-Video by setting the WATCH_DETAIL variable in your .env file. Choose from transcript, efficient, or token-burner options.

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

---

**Set the `WATCH_DETAIL` environment variable in `~/.config/watch/.env` to override the built-in default of `balanced` with `transcript`, `efficient`, or `token-burner`.**

The `bradautomates/claude-video` repository provides a video analysis framework that extracts frames using configurable detail strategies. Instead of passing `--detail` flags for every command, you can establish a persistent default through a local environment file, eliminating repetitive CLI arguments while customizing frame extraction behavior for your specific workflow.

## Understanding Detail Modes in Claude-Video

The **detail mode** controls how aggressively the system samples frames from video content—balancing token usage against visual comprehension. According to [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the library recognizes four distinct extraction strategies defined in the `DETAILS` set:

- **`transcript`** – Processes audio only, skipping visual frame extraction entirely
- **`efficient`** – Minimal frame sampling for cost-conscious processing
- **`balanced`** – Scene-aware sampling at 2 FPS maximum with a 100-frame cap (default)
- **`token-burner`** – Maximum frame extraction for highest visual fidelity

The built-in default is hardcoded as `DEFAULT_DETAIL = "balanced"` at line 12 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

## Locating the Configuration File

The configuration system loads key-value pairs from `~/.config/watch/.env` using `python-dotenv`. This file location takes precedence over system-wide environment variables during the resolution chain documented in lines 52-57 of the config module.

## Setting WATCH_DETAIL in .env

### Creating the Configuration Directory

Create the directory structure if it does not exist, then open the environment file:

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

```

### Valid Detail Mode Values

Add the `WATCH_DETAIL` variable to your `.env` file:

```text
WATCH_DETAIL=efficient

```

Supported values must match the set defined in the source: `transcript`, `efficient`, `balanced`, or `token-burner`. Lines beginning with `#` are treated as comments:

```text
WATCH_DETAIL=balanced   # default – scene-aware frames, 2 fps max, 100-frame cap

```

## How the Configuration Resolution Works

As implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the resolution follows a strict priority order:

1. **Environment Variable Check** – The code first inspects the process environment for `WATCH_DETAIL` (lines 52-57)
2. **`.env` File Loading** – If absent from the environment, it loads from `~/.config/watch/.env` via `load_dotenv()`
3. **Validation** – The value is checked against `DETAILS = {"transcript", "efficient", "balanced", "token-burner"}`; unknown values trigger fallback behavior
4. **Default Fallback** – Invalid or missing values resolve to `DEFAULT_DETAIL = "balanced"` (line 12)
5. **API Exposure** – The final string is exposed through `config.get_config()["detail"]` and consumed by [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) using `detail = args.detail or str(config["detail"])`

## Verifying Your Configuration

Confirm your environment setup using Python:

```python
from skills.watch.scripts import config

cfg = config.get_config()
print("Effective detail mode:", cfg["detail"])

```

Run the CLI without the `--detail` flag to verify automatic application:

```bash
watch https://www.youtube.com/watch?v=example

```

The command executes as if you had explicitly passed `--detail efficient` (or whichever mode you configured).

## Summary

- The default detail mode is **`balanced`**, defined as a constant in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) at line 12
- Set **`WATCH_DETAIL`** in `~/.config/watch/.env` to override the default permanently across sessions
- Valid options are strictly limited to: `transcript`, `efficient`, `balanced`, and `token-burner`
- Configuration resolution validates inputs and exposes the final value via `config.get_config()["detail"]`
- Explicit CLI flags (`--detail`) override `.env` settings for single-command exceptions

## Frequently Asked Questions

### What happens if I set an invalid detail mode in .env?

The validation logic in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) checks the `WATCH_DETAIL` value against the supported `DETAILS` set. If the value is invalid or the variable is missing, the system falls back to the built-in default of `balanced` defined at line 12.

### Can I override the .env default for a single command?

Yes. The CLI `--detail` flag takes precedence over environment variables. According to the implementation in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), the resolution uses `args.detail or str(config["detail"])`, meaning explicit command-line arguments override `.env` configurations for that specific execution.

### Where is the default detail mode defined in the source code?

The constant `DEFAULT_DETAIL = "balanced"` is explicitly defined at line 12 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). This value serves as the fallback when `WATCH_DETAIL` is unset, missing from the `.env` file, or contains an unsupported value.

### Do I need to restart my terminal after editing .env?

No. The `load_dotenv()` function reads the `.env` file fresh each time the Python process initializes. Changes take effect immediately for new `watch` commands or Python sessions without requiring terminal restarts or shell configuration reloads.