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

> Configure the default detail mode in Claude-Video by setting the WATCH_DETAIL environment variable in ~/.config/watch/.env. Choose from transcript, efficient, balanced, or token-burner modes.

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

---

**Set the `WATCH_DETAIL` environment variable in `~/.config/watch/.env` to control how many frames the watch skill extracts from videos, choosing from `transcript`, `efficient`, `balanced`, or `token-burner`.**

The `bradautomates/claude-video` repository provides a watch skill that processes video content with adjustable visual detail levels. Rather than passing flags to every command, you can configure the default detail mode permanently by creating a environment file at `~/.config/watch/.env`.

## Understanding the Four Detail Modes

The watch skill uses a **detail dial** that determines frame extraction density. According to the source code in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), you can select one of four modes:

- **`transcript`** – Extracts no frames; returns only timestamped text transcripts.
- **`efficient`** – Fast key-frame extraction with an approximate 50-frame cap.
- **`balanced`** – Scene-aware extraction with an approximate 100-frame cap. This is the **hard-coded default** defined on line 12 of [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py).
- **`token-burner`** – Scene-aware extraction with **no** frame cap, providing maximum visual detail.

## Locating the Configuration File

The tool reads persistent configuration from **`~/.config/watch/.env`** using the `python-dotenv` package. This location follows the XDG Base Directory specification and applies globally to all watch skill invocations on your system.

If the directory does not exist, create it:

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

```

## Setting the Default Detail Mode

To change the default behavior, define the `WATCH_DETAIL` variable in your environment file.

### Step 1: Create or Edit the Environment File

Open `~/.config/watch/.env` in your preferred editor:

```bash
nano ~/.config/watch/.env

```

### Step 2: Add the WATCH_DETAIL Variable

Choose your preferred mode and add it to the file:

```text

# ~/.config/watch/.env

WATCH_DETAIL=efficient

```

Or for maximum detail:

```text

# ~/.config/watch/.env

WATCH_DETAIL=token-burner

```

Save the file. The change takes effect immediately for the next watch skill execution.

## How the Configuration Resolution Works

The precedence logic is implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) within the `get_config()` function (lines 37–53). The code checks three sources in order:

1. **Environment variable** (`os.environ.get("WATCH_DETAIL")`) – Highest priority, allowing temporary overrides.
2. **File values** (`file_values.get("WATCH_DETAIL")`) – Values loaded from `~/.config/watch/.env` via `load_dotenv`.
3. **Hard-coded default** (`DEFAULT_DETAIL`) – Falls back to `"balanced"` if no other value is found.

This hierarchy means your `.env` file setting persists across sessions, but you can still override it temporarily using shell environment variables or command-line flags.

## Verifying Your Configuration

You can confirm the active default by importing the configuration module directly:

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

cfg = config.get_config()
print("Current default detail:", cfg["detail"])

```

If your `.env` file contains `WATCH_DETAIL=efficient`, the output shows:

```text
Current default detail: efficient

```

## Summary

- The **default detail mode** in `bradautomates/claude-video` is controlled by the `WATCH_DETAIL` environment variable.
- Create **`~/.config/watch/.env`** and set `WATCH_DETAIL` to `transcript`, `efficient`, `balanced`, or `token-burner`.
- The resolution order is: shell environment > `.env` file > hard-coded `"balanced"` default (defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)).
- Command-line flags take precedence over the `.env` file for one-off overrides.

## Frequently Asked Questions

### What happens if I don't set WATCH_DETAIL in the .env file?

If `~/.config/watch/.env` does not exist or lacks the `WATCH_DETAIL` variable, the tool falls back to the hard-coded `DEFAULT_DETAIL = "balanced"` constant defined at line 12 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

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

Yes. You can pass the `--detail` flag on the command line, which takes precedence over both the environment variable and the `.env` file. For example: `watch https://youtu.be/example --detail token-burner`.

### What's the difference between efficient and token-burner modes?

**`efficient`** caps extraction at approximately 50 key frames for speed and lower token usage, while **`token-burner`** uses scene-aware detection with no frame limit, extracting every significant visual change regardless of cost or processing time.

### Where is the configuration precedence defined in the source code?

The precedence logic appears in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) at lines 37–53 inside the `get_config()` function, where the code explicitly checks `os.environ`, then `file_values` (populated by `load_dotenv`), then the `DEFAULT_DETAIL` fallback.