Skip to main content
otter-settings edits Otter Shell configuration through app-specific tabs, a theme browser, and a drag-and-drop bar layout. You can also edit the same files in $EDITOR.

​
Usage

Launch from otter-launcher or bind a compositor hotkey (for example Super+Comma). Settings only shows app tabs whose matching Otter executable is installed. Theme, Plugins, and UI Scripts stay available. Restart Settings after installing or removing a component so it can refresh the sidebar.
Writes to ~/.config/otter-shell/*.conf. Running apps reload via inotify after Apply.

​
What otter-settings handles

​
Config files managed

Bar layout is drag-and-drop. You can add custom bar buttons. Text fields accept clipboard paste (Ctrl+V) through the Wayland data device.

​
Wallpaper picker

Open the wallpaper grid directly from a keybinding:
Click an image to apply it, or press Escape to close. See otter-wallpaper.

​
Theme Gen tab

The Theme Gen tab edits otter-theme-gen.conf. The otter-theme-gen daemon ships with otter-shell. Autostart it with otter-wallpaper so it can read $XDG_RUNTIME_DIR/otter-shell/wallpaper-state and update generated-colors.conf. On the tab:
  • Enabled: turn wallpaper-reactive theming on or off
  • Mode: dark or light palette
  • Islands mode: Otter Shell Islands surface styling
  • Strategy: how colors are pulled from the wallpaper (material_you, analogous, vibrant, monochromatic, direct, temperature)
  • Contrast, Vibrancy, and Opacity: tune the generated palette
  • Background blur: request compositor blur behind translucent Otter surfaces
  • Templates: pick which third-party configs get rewritten (terminals, GTK, Hyprland Lua at ~/.config/hypr/otter-theme.lua, bottom, btop, KDE color schemes, Papirus folder colors, and others)
Turn on only the templates you want overwritten. Click Apply to save. For fixed presets instead, see Themes. See otter-theme-gen for daemon details.

​
Monitor tab

The Monitor tab edits otter-monitor.conf for otter-monitor:
  • Refresh interval seconds: how often the collector polls /proc and sysfs (1 to 3600)
Restart otter-monitor after you change the refresh interval. Theme colors still hot-reload from theme.conf.

​
Clicker tab

The Clicker tab edits otter-clicker.conf for otter-clicker. Set the interval, button, single or double click, repeat count, jitter, hold time, and fixed-position mode.

​
Assist tab

The Assist tab edits otter-assist.conf for the otter-assist daemon (from otter-shell-extras):
  • Backend: cpu or vulkan
  • Vulkan device: GPU index, or -1 for llama.cpp auto selection
  • Idle seconds: unload the idle model after this many seconds (default 120)
  • Tool toggles and always-allow flags for knowledge, web, weather, and desktop search
  • Pika search URL, knowledge index path, and tool-call budgets
Full key list: otter-assist. The chat client keeps its own file, otter-assistant.conf, for window size, generation limits, and UI always-allow flags.

​
What otter-settings does not configure

Compositor hotkeys (launcher, overview, screenshot, lock) belong in your Wayland compositor config. See Keybinds. otter-screenshot has no persistent config file. CLI flags only.

​
Theme presets

Otter Shell, Otter Shell Islands, Catppuccin variants, Nord, Gruvbox, Dracula, Tokyo Night, and One Dark. Settings writes the selected preset colors to preset-colors.conf and imports that file from root theme.conf. It does not flatten preset colors into your root overrides. See Themes for color token details.

​
Plugins tab

The Plugins tab discovers Lua plugin directories through their plugin.toml manifests. Compiled .so plugins are not supported. You can enable plugins, allow or deny each declared capability, and request a reload. Apply writes the enable flags and capability grants to plugins.conf. Running hosts can report load status, granted capabilities, heap use, reloads, failures, and their latest error or log message. Missing status means no running host has reported it, not that a plugin passed a health check. Enabled bar plugins also appear as plugin:<id> chips in the bar layout palette. See Plugins.

​
UI Scripts tab

The UI Scripts tab manages Lua-drawn app surfaces such as osd.lua and logout.lua. It shows the system script, any user override, and runtime status when the app reports it.
  • Create override copies a system script to your XDG data directory, normally ~/.local/share/otter-shell/ui/.
  • Reset to system moves your override aside so the system script takes over.
  • Native UI disables the script for that app.
  • Hot reload controls automatic script reloads.
  • Reload now is available for apps that support it, including OSD.
Click Apply to save per-app mode and hot-reload choices in ~/.config/otter-shell/ui.conf. Layout, hit testing, and rendering remain native even when Lua describes the surface.

​
Overview tab

The Overview tab edits otter-overview.conf for otter-overview: card axis and scale, empty-workspace policy, thumbnail capture, and optional colors.

​
Dock and Taskbar tabs

Dock edits otter-dock.conf. Taskbar edits otter-taskbar.conf. Both are optional session components. See otter-dock and otter-taskbar.

​
Night Light tab

The Night Light tab edits otter-nightlight.conf. Autostart the otter-nightlight daemon so the bar widget and Settings can talk to it.

​
Files tab

The Files tab edits otter-files.conf when otter-files is on PATH. It controls view mode, sorting, thumbnails, and confirmation dialogs. See otter-files.