Configuration

Configuration

UnixNotis loads config.toml from the XDG config directory and hot-reloads it on change.

Config file

Locations:

• $XDG_CONFIG_HOME/unixnotis/config.toml
• fallback: $HOME/.config/unixnotis/config.toml

If the file is missing, built-in defaults are used. Unknown keys are ignored and logged. Runtime sanitization clamps out-of-range values to safe limits.

Reload behavior

• The daemon, panel, and popup UIs watch for config changes.
• Updates are applied without restarting the service.
• Reload failures keep the previous valid configuration.

Minimal example

[general]
log_level = "info"
dnd_default = false

[inhibit]
mode = "no_popups"

[panel]
anchor = "right"
width = 420
empty_text = "NO NOTIFICATIONS"
empty_offset_top = 120

[popups]
anchor = "top-right"
width = 360

[theme]
base_css = "base.css"
popup_css = "popup.css"
panel_css = "panel.css"
widgets_css = "widgets.css"

Defaults snapshot (widgets)

The default panel includes:

• Sliders: Volume, Brightness
• Toggles: Wi-Fi, Bluetooth, Airplane, Night
• Stats: CPU, RAM, Battery
• Cards: Calendar, Weather (static unless configured)

See Widgets for the full schema and default command backends.

Section reference

[general]

• log_level: tracing filter syntax (RUST_LOG compatible).
• dnd_default: default DND state when no persisted state exists.

[inhibit]

• mode: no_popups (store notifications, suppress popups) or drop_all.

[panel]

• anchor: top-right, top-left, bottom-right, bottom-left, top, bottom, left, right.
• width: width in logical pixels.
• height: 0 uses compositor-driven height.
• keyboard_interactivity: none, on-demand, exclusive.
• output: optional Wayland output name.
• close_on_blur: hide when the panel loses focus.
• close_on_click_outside: hide on outside click (Hyprland only).
• respect_work_area: respects compositor reserved area (Hyprland only).
• empty_text: empty-state label text (supports \n for multi-line).
• empty_offset_top: top offset when widgets are visible. When no widgets are visible, the empty state is centered in the list area.
• [panel.margin]: margins in logical pixels.

Defaults:

• empty_text = "NO NOTIFICATIONS"
• empty_offset_top = 120

[popups]

• anchor, width, spacing, max_visible.
• default_timeout_ms, critical_timeout_ms.
• allow_click_through: disable input handling when true.
• output: optional Wayland output name.
• [popups.margin]: margins in logical pixels.

[history]

• max_entries: history capacity.
• max_active: active list capacity.
• transient_to_history: includes transient notifications in history.

[media]

• enabled, include_browsers.
• browser_tokens: case-insensitive tokens used to classify browser players.
• title_char_limit: marquee starts after this length.
• allowlist / denylist: case-insensitive substrings for player identities.

Defaults:

• browser_tokens includes common desktop browsers (Firefox, Chromium, Chrome, Brave, Vivaldi, Edge, Opera, Epiphany, Midori, Zen, Librewolf, Waterfox, Floorp).
• title_char_limit = 32.

[sound]

• enabled.
• default_name: freedesktop sound theme name.
• default_file: sound file path (relative to config dir when not absolute).
• default_dir: directory containing sound files.

[theme]

Theme CSS file names resolve relative to the config directory. Alpha values are clamped to 0.0..=1.0 and dimensions are clamped to safe ranges.

• border_width: card/control border thickness.
• card_radius: card corner radius.
• surface_alpha, surface_strong_alpha, card_alpha.
• shadow_soft_alpha, shadow_strong_alpha.

[widgets]

• refresh_interval_ms: base refresh interval for widget polling.
• refresh_interval_slow_ms: slower interval used during stable periods.
• [[widgets.stats]].plugin: optional external plugin for stat values.
• [[widgets.cards]].plugin: optional external plugin for card content.

Plugin block fields:

• api_version: plugin contract version (currently 1).
• command: simple executable command (no shell metacharacters).
• timeout_ms: plugin runtime timeout in milliseconds.
• max_output_bytes: maximum accepted plugin stdout payload size.

See Widgets for the widget schema and command examples.

rules

Rules match notification fields and apply overrides. See Rules for details and examples.