> ## 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.

# otter-theme-gen

> Wallpaper-reactive themes for Otter Shell. Extracts palette colors from your wallpaper and writes generated-colors.conf.

`otter-theme-gen` watches your wallpaper and writes matching colors to `generated-colors.conf`. It ships in the `otter-shell` metapackage. Configure it from the **Theme Gen** tab in [otter-settings](/desktop/otter-settings), or edit `otter-theme-gen.conf` by hand.

## Usage

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

Autostart it with [otter-wallpaper](/desktop/otter-wallpaper). Theme generation needs wallpaper state from `$XDG_RUNTIME_DIR/otter-shell/wallpaper-state`.

```bash theme={null}
otter-wallpaper &
otter-theme-gen &
```

See [Session setup](/desktop/session-setup).

## How it works

1. [otter-wallpaper](/desktop/otter-wallpaper) writes the current image path per output to `wallpaper-state`.
2. `otter-theme-gen` reads that file, extracts a palette, and updates `~/.config/otter-shell/generated-colors.conf`.
3. Apps watching the theme import graph pick up the new colors. [otter-term](/apps/otter-term) hot-reloads shared theme changes without a restart.

The daemon skips work when the wallpaper hash has not changed.

## Configuration

Config file: `~/.config/otter-shell/otter-theme-gen.conf`

Generated color layer: `~/.config/otter-shell/generated-colors.conf`

```conf theme={null}
enabled = true
mode = dark
islands_mode = false
strategy = material_you
contrast = 0.7
vibrancy = 0.6
global_opacity = 96
```

| Key              | Default        | Description                                                                   |
| ---------------- | -------------- | ----------------------------------------------------------------------------- |
| `enabled`        | `true`         | Turn wallpaper-reactive theming on or off                                     |
| `mode`           | `dark`         | `dark` or `light` palette                                                     |
| `islands_mode`   | `false`        | Make the Bar rail transparent and give each section its own generated surface |
| `strategy`       | `material_you` | Palette extraction style                                                      |
| `contrast`       | `0.7`          | Palette contrast (0.0 to 1.0)                                                 |
| `vibrancy`       | `0.6`          | Palette vibrancy (0.0 to 1.0)                                                 |
| `global_opacity` | `96`           | Panel and surface opacity (0 to 100)                                          |

`strategy` options: `material_you`, `analogous`, `vibrant`, `monochromatic`, `direct`, `temperature`.

With `islands_mode = true`, gaps between Bar sections stay clear. When blur is enabled, each section clips blur to its own surface.

## Template outputs

Optional template keys rewrite third-party config files when colors change. All templates start disabled. Enable only the apps you want synced.

```conf theme={null}
template_gtk3_enabled = true
template_hyprland_enabled = true
template_kcolorscheme_enabled = true
template_papirus_colors_enabled = true
```

Shipped templates cover terminals, GTK, Hyprland (`~/.config/hypr/otter-theme.lua`), `bottom`, btop, KDE color schemes, Papirus folder colors, and more. Toggle them in the **Theme Gen** tab in otter-settings.

### KDE color schemes

Enable `template_kcolorscheme_enabled` to write `~/.local/share/color-schemes/Otter.colors` and sync related keys through `kdeglobals`. When KDE CLI tools are installed, the daemon can refresh the live session too.

### Papirus folder colors

Enable `template_papirus_colors_enabled` to create and select a user-owned `Otter-Papirus-*` icon theme for GTK and Qt. It inherits installed Papirus icons and points folder names at the closest Papirus color variant. No root and no writes under `/usr/share`. Papirus must already be installed.

<Tip>
  `otter-theme-gen` never rewrites root `theme.conf`. It reads the selected profile and root overrides, then writes color keys only to `generated-colors.conf`.
</Tip>

## Templates on disk

Installed templates live under `/usr/share/otter-shell/theme-gen/templates/`.