# How the `~/.config/watch/.env` Configuration File Works in Claude-Video

> Understand the ~/.config/watch/.env configuration file for Claude-Video. Learn how it stores user settings, manages defaults, and allows overrides for frame extraction.

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

---

**The `~/.config/watch/.env` file stores user settings for the `/watch` command, parsed by [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) to provide persistent defaults for frame extraction behavior while allowing overrides via environment variables or CLI flags.**

The `bradautomates/claude-video` repository uses a local dotenv file to manage user preferences for video analysis. Located at `$HOME/.config/watch/.env`, this configuration file controls how many frames Claude extracts from videos based on the `WATCH_DETAIL` setting.

## Configuration File Location and Structure

Claude-Video defines its configuration paths as constants in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

### Default Paths

The module constructs the configuration directory and file paths using Python's `pathlib`:

```python
CONFIG_DIR = Path.home() / ".config" / "watch"
CONFIG_FILE = CONFIG_DIR / ".env"

```

These definitions appear at lines 9–11 of [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py). If the directory does not exist, the application handles its creation as needed when writing or reading the configuration.

## Parsing the Dotenv File

The configuration parser handles standard dotenv syntax while preserving special characters in values.

### The read_env_file Function

Located at lines 17–45 of [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `read_env_file` function processes the `.env` file with specific parsing rules:

- Splits content into individual lines and skips blank entries
- Strips surrounding quotes from quoted values (both single and double)
- Removes inline comments (`# comment`) **only** from unquoted values, preserving `#` characters inside quoted strings such as API keys

- Extracts `KEY=VALUE` pairs into a dictionary

This implementation ensures that values like `GROQ_API_KEY="sk-xxx#123"` retain the hash character, while unquoted values like `WATCH_DETAIL=efficient # quick mode` have the comment stripped.

## Runtime Configuration with get_config

The `get_config` function at lines 48–62 builds the final configuration dictionary by merging file-based settings with system environment variables.

### WATCH_DETAIL Variable and Defaults

The `WATCH_DETAIL` setting controls frame extraction behavior and supports four valid values:

| Detail Level | Frame Behavior |
|-------------|----------------|
| `efficient` | Caps at 50 frames |
| `balanced` | Caps at 100 frames |
| `token-burner` | Unlimited frames (no cap) |
| `transcript` | No frames extracted (audio-only) |

The function checks for `WATCH_DETAIL` in the following precedence:
1. Real OS environment variables (highest priority among persistent settings)
2. Keys defined in `~/.config/watch/.env`
3. Built-in default of `"balanced"` (lowest priority)

Invalid values automatically normalize back to `"balanced"`.

### Frame Cap Mapping

The `frame_cap` dictionary at lines 65–74 maps detail levels to integer limits:

```python
frame_cap = {
    "efficient": 50,
    "balanced": 100,
    "token-burner": float("inf"),
    "transcript": 0
}

```

The `get_config` function returns a dictionary containing the resolved `detail` value and the absolute path to `config_file`, enabling other modules to verify which configuration source is active.

## Overriding Configuration Values

The `/watch` entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (line 71) calls `get_config()` and merges the result with command-line arguments:

```python
config = get_config()
detail = args.detail or str(config["detail"])

```

This merge strategy allows temporary overrides without modifying the configuration file. You can set persistent defaults in the `.env` file, override them via environment variables for a session, or use `--detail` flags for single-command adjustments.

## Configuration Precedence and Overrides

Claude-Video applies settings through a strict hierarchy where higher levels override lower ones:

1. **CLI arguments** (`--detail token-burner`) – Immediate, single-use override
2. **OS environment variables** (`export WATCH_DETAIL=efficient`) – Session-level override
3. **Dotenv file** (`~/.config/watch/.env`) – Persistent user defaults
4. **Hardcoded defaults** – Fallback when no user configuration exists

For example, to temporarily analyze a video with maximum detail extraction while keeping `balanced` as your default:

```bash
watch https://example.com/video.mp4 --detail token-burner

```

Or to set a session-wide efficient mode:

```bash
export WATCH_DETAIL=efficient
watch https://example.com/video.mp4

```

## Summary

- The `~/.config/watch/.env` file stores persistent configuration for the `/watch` command in `bradautomates/claude-video`
- [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) provides `read_env_file` for parsing and `get_config` for resolving configuration values
- `WATCH_DETAIL` accepts `efficient`, `balanced`, `token-burner`, or `transcript`, defaulting to `balanced` when invalid or unspecified
- The `frame_cap` dictionary maps detail levels to frame limits (50, 100, unlimited, or zero)
- Configuration precedence follows: CLI flags > OS environment variables > `.env` file > built-in defaults

## Frequently Asked Questions

### Where is the claude-video configuration file stored?

The configuration file is located at `$HOME/.config/watch/.env` on Unix-like systems. The path is constructed in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) using `Path.home() / ".config" / "watch" / ".env"`, ensuring it resides in the user's home directory under the standard XDG configuration path.

### What values can I set for WATCH_DETAIL?

Valid `WATCH_DETAIL` values include `efficient` (50 frames), `balanced` (100 frames), `token-burner` (unlimited frames), and `transcript` (zero frames, audio-only). Any other value automatically normalizes to `balanced`. These mappings are defined in the `frame_cap` dictionary at lines 65–74 of [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py).

### Can I use environment variables instead of the .env file?

Yes. Real OS environment variables take precedence over the `.env` file but yield to CLI flags. You can `export WATCH_DETAIL=efficient` in your shell session to override the file-based setting without modifying `~/.config/watch/.env`.

### How do I override the detail level for a single command?

Pass the `--detail` flag to the `watch` command. For example, `watch https://example.com/video.mp4 --detail token-burner` temporarily uses unlimited frame extraction regardless of your `.env` file or environment variable settings. This override logic is implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at line 71.