# How to Set the Default Detail Mode in claude-video Using ~/.config/watch/.env

> Persist your claude-video default detail mode using WATCH_DETAIL in ~/.config/watch/.env Avoid exporting variables every session Learn simple setup now

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

---

**Add `WATCH_DETAIL=<mode>` to `~/.config/watch/.env` to persist your preferred detail setting across all claude-video invocations without exporting environment variables in every shell session.**

The claude-video project (available at `bradautomates/claude-video`) provides a flexible configuration system for controlling video frame extraction through "detail modes." Rather than passing flags on every command, you can persist your preferred setting by configuring the **WATCH_DETAIL** variable in a dedicated environment file.

## Understanding the Configuration Precedence

Claude-video resolves the active detail mode through a three-tier fallback system defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). The hierarchy follows this priority order:

1. **Shell environment variables** - An exported `WATCH_DETAIL` takes highest precedence
2. **User configuration file** - The `WATCH_DETAIL` key in `~/.config/watch/.env` (parsed at lines 9-11)
3. **Hard-coded default** - Falls back to `balanced` (defined in `DEFAULT_DETAIL` at lines 12-14)

When the configuration loader runs, it merges these sources in the `get_config()` function (lines 51-55), with later sources overriding earlier ones.

## Setting WATCH_DETAIL in ~/.config/watch/.env

To establish a permanent default, create or edit the configuration file at `~/.config/watch/.env`.

### Supported Detail Modes

According to lines 14-15 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), valid values include:

- `transcript` - Minimal frame extraction optimized for transcript-only analysis
- `efficient` - Reduced frame sampling for faster processing
- `balanced` - Default moderate sampling (defined in `DEFAULT_DETAIL` at line 12)
- `token-burner` - Maximum frame density for detailed visual analysis

### Creating the Configuration File

Create the directory and file if they don't exist:

```bash
mkdir -p ~/.config/watch
echo "WATCH_DETAIL=efficient" > ~/.config/watch/.env

```

The parser (line 27 in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py)) reads each non-comment line as `KEY=VALUE` pairs. Lines beginning with `#` are ignored as comments.

Example configuration:

```text

# ~/.config/watch/.env

# Options: transcript, efficient, balanced, token-burner

WATCH_DETAIL=efficient

```

## Verifying Your Configuration

Inspect the active configuration through Python to confirm the file is loading correctly:

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

cfg = config.get_config()
print(cfg["detail"])  # Outputs: "efficient"

```

If the file contains an invalid value, the system falls back to `balanced` (line 57), protecting against configuration errors.

## Overriding Defaults Temporarily

Even with a persisted configuration, you can override the detail mode for single invocations by setting the shell environment variable:

```bash

# Overrides ~/.config/watch/.env for this command only

WATCH_DETAIL=token-burner claude-video /watch "https://youtu.be/example"

```

This temporary override takes precedence over the file-based configuration per the merging logic in `get_config()`.

## Summary

- **Configuration file location:** `~/.config/watch/.env`
- **Key variable:** `WATCH_DETAIL` (validated against accepted modes in lines 14-15 of [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py))
- **Precedence order:** Shell environment > Config file > Default (`balanced`)
- **Validation:** Invalid values fall back to `balanced` at line 57 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)
- **Syntax:** Standard KEY=VALUE format with `#` for comments (parsed at line 27)

## Frequently Asked Questions

### What happens if I set an invalid detail mode in ~/.config/watch/.env?

If you specify a value not in the allowed set (`transcript`, `efficient`, `balanced`, `token-burner`), the configuration loader at line 57 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) automatically falls back to the `balanced` default. The application will run without errors, but will use the fallback setting instead of your invalid entry.

### Can I use claude-video without creating the ~/.config/watch/.env file?

Yes. The configuration system is optional. If `~/.config/watch/.env` does not exist, or if it exists but lacks a `WATCH_DETAIL` entry, claude-video defaults to `balanced` mode as defined by `DEFAULT_DETAIL` at lines 12-14 of [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py).

### Does the WATCH_DETAIL environment variable override the config file?

Yes. The merging logic in `get_config()` (lines 51-55) prioritizes shell environment variables over file-based settings. If you export `WATCH_DETAIL` in your shell, it will supersede any value set in `~/.config/watch/.env` for that session.

### Where is the detail setting actually consumed in the codebase?

The entry point [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) imports and calls `config.get_config()`, which returns a dictionary containing the resolved `detail` key. This value then controls frame extraction behavior throughout the video processing pipeline.