> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration overview

> Configure Otter Shell in otter-settings or by editing ~/.config/otter-shell/. Most changes hot-reload on save.

**`otter-settings`** is the main config UI: one tab per app, a theme browser, and drag-and-drop bar layout. It writes the same `~/.config/otter-shell/*.conf` files as manual edits, so GUI and text stay in sync.

```bash theme={null}
otter-settings
```

Launch from [otter-launcher](/desktop/otter-launcher), bind a compositor hotkey, or run the command above. See [otter-settings](/desktop/otter-settings) for tabs, features, and theme presets.

<Note>
  Click **Apply** and most running apps reload via inotify. No restart needed.
</Note>

## What you can configure in otter-settings

| Tab                                  | What you edit                                          |
| ------------------------------------ | ------------------------------------------------------ |
| Bar                                  | Widget layout, clock, volume, tray, custom buttons     |
| Launcher                             | Size, colors, placeholder text                         |
| Notifications                        | Position, timeouts, margins                            |
| Wallpaper                            | Path, rotation, scale mode                             |
| OSD                                  | Volume/brightness overlay appearance                   |
| Terminal                             | Fonts, colors, padding, keybinds                       |
| Theme                                | Colors, spacing, presets (12 built-in themes)          |
| Theme Gen                            | Wallpaper-reactive themes, opacity, template outputs   |
| Monitor                              | System monitor refresh interval                        |
| Assist                               | `otter-assist` backend (`otter-shell-extras`)          |
| Clicker                              | Auto-clicker interval, button, and fixed-position mode |
| Lock / Logout / Idle / Polkit / Jade | Session and overlay settings                           |
| Recorder / Voice                     | `otter-rec` and `otter-vox` options                    |

Compositor hotkeys (screenshot, launcher, lock) are **not** in otter-settings. Bind those in your compositor config. See [Keybinds](/configuration/keybinds).

## Manual config files

Each app has a plain-text file in `~/.config/otter-shell/`. Edit by hand to script changes or keep custom comments the UI might not show.

| App                 | Config file                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| Shared theme        | `~/.config/otter-shell/theme.conf`                                        |
| otter-bar           | `~/.config/otter-shell/otter-bar.conf`                                    |
| otter-launcher      | `~/.config/otter-shell/otter-launcher.conf`                               |
| otter-notifications | `~/.config/otter-shell/notifications.conf`                                |
| otter-wallpaper     | `~/.config/otter-shell/otter-wallpaper.conf`                              |
| otter-theme-gen     | `~/.config/otter-shell/otter-theme-gen.conf`                              |
| otter-osd           | `~/.config/otter-shell/otter-osd.conf`                                    |
| otter-logout        | `~/.config/otter-shell/otter-logout.conf`                                 |
| otter-polkit        | `~/.config/otter-shell/otter-polkit.conf`                                 |
| otter-lock          | `~/.config/otter-shell/otter-lock.conf`                                   |
| otter-idle          | `~/.config/otter-shell/otter-idle.conf`                                   |
| otter-jade          | `~/.config/otter-shell/otter-jade.conf`                                   |
| otter-term          | `~/.config/otter-shell/otter-term.conf`                                   |
| otter-monitor       | `~/.config/otter-shell/otter-monitor.conf`                                |
| otter-assist        | `~/.config/otter-shell/otter-assist.conf` *(via `otter-shell-extras`)*    |
| otter-assistant     | `~/.config/otter-shell/otter-assistant.conf` *(via `otter-shell-extras`)* |
| otter-rec           | `~/.config/otter-shell/otter-rec.conf`                                    |
| otter-clip          | `~/.config/otter-shell/otter-clip.conf`                                   |
| otter-note          | `~/.config/otter-shell/otter-note.conf`                                   |
| otter-cal           | `~/.config/otter-shell/otter-cal.conf`                                    |
| otter-timer         | `~/.config/otter-shell/otter-timer.conf`                                  |
| otter-transcribe    | `~/.config/otter-shell/otter-transcribe.conf`                             |
| otter-calc          | `~/.config/otter-shell/otter-calc.conf`                                   |
| otter-emoji         | `~/.config/otter-shell/otter-emoji.conf`                                  |
| otter-pick          | `~/.config/otter-shell/otter-pick.conf`                                   |
| otter-clicker       | `~/.config/otter-shell/otter-clicker.conf`                                |
| otter-vox           | `~/.config/otter-shell/otter-vox.conf`                                    |
| otter-weather       | `~/.config/otter-shell/otter-weather.conf`                                |
| otter-screenshot    | *(no persistent config: CLI flags only)*                                  |

System defaults may live under `/etc/otter-shell/`. User configs always win.

## File format

```conf theme={null}
# Comments start with #
font_size = 14
font_family = "IoskeleyMono Nerd Font"
url_enabled = true
```

Quote strings with double quotes. Booleans are `true` or `false`. Empty string `""` falls back to the compiled default.

On first launch, apps normalize their config: missing keys get defaults, unknown keys are removed.

## Hot reload

Most daemons watch their config (and often `theme.conf`) with inotify:

* **otter-bar**: reloads `otter-bar.conf` on save; `theme.conf` changes refresh widget colors without a full bar config reload
* **otter-notifications**, **otter-wallpaper**, **otter-osd**, **otter-idle**: reload on save
* **otter-term**: hot-reloads `otter-term.conf` and shared `theme.conf`
* **otter-monitor**: hot-reloads `theme.conf` only; restart to pick up `otter-monitor.conf` changes
* **otter-transcribe**: reloads settings and watches `theme.conf`; restarts automatically after a model unload when idle

otter-settings and manual saves hit the same reload path.

## System-wide defaults

Lookup order (example for `otter-term`):

1. `~/.config/otter-shell/otter-term.conf` *(user: highest priority)*
2. `/etc/otter-shell/otter-term.conf` *(system defaults)*
3. Compiled-in defaults

Set system defaults in `/etc/otter-shell/` without touching home directories.