Configuration overview

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 you would edit by hand, so the GUI and text stay in sync.

otter-settings

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

Click Apply and most running apps reload via inotify. No restart needed.

What you can configure in otter-settings

Tab	What you edit
Bar	Widget layout, clock, volume, tray, custom buttons
Launcher	Size, colors, placeholder text
Plugins	Enable or disable installed `.so` plugins
Dock	Magnification dock layout and pinned apps
Taskbar	Taskbar height, clock, tray, pinned apps
Overview	Workspace overview card size, axis, captures
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
Files	File manager view, sort, thumbnails, confirms
Night Light	Schedule and color temperature
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, overview, lock) are not in otter-settings. Bind those in your compositor config. See Keybinds.

Manual config files

Each app has a plain-text file in ~/.config/otter-shell/. Edit by hand when you want to script changes, or keep 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`
Plugins	`~/.config/otter-shell/plugins.conf`
otter-overview	`~/.config/otter-shell/otter-overview.conf`
otter-dock	`~/.config/otter-shell/otter-dock.conf`
otter-taskbar	`~/.config/otter-shell/otter-taskbar.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-nightlight	`~/.config/otter-shell/otter-nightlight.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-files	`~/.config/otter-shell/otter-files.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)
otter-pkg	(app state under `$XDG_STATE_HOME/otter-pkg/`, not otter-conf)
otter-keybindhelp	(reads compositor configs; no otter-conf file)

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

File format

# 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):

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

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

Get Started

Desktop Shell

Core Apps

Productivity

Utilities

Gaming

Configuration

Configuration overview

What you can configure in otter-settings

Manual config files

File format

Hot reload

System-wide defaults

​What you can configure in otter-settings

​Manual config files

​File format

​Hot reload

​System-wide defaults

What you can configure in otter-settings

Manual config files

File format

Hot reload

System-wide defaults