✓ Stable v0.1.0

garnotify

FreeDesktop-compliant notification daemon with rules and history

garnotify is a notification daemon for the gardesk ecosystem that implements the FreeDesktop Desktop Notifications Specification 1.2. It features configurable popup positioning, per-urgency timeouts and colors, a powerful rule engine for filtering and modifying notifications, persistent history, Do Not Disturb modes, and smooth animations. Integrates with gar's Lua configuration for unified desktop setup.

View on GitHub Download RPM

🎯 RPM Available

Installation

garnotify is available as an RPM package for Fedora and RHEL-compatible distributions.

Using DNF (Recommended)

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garnotify

Building from Source

$git clone https://github.com/espadon/gardesk

$cd gardesk/garnotify

$cargo build --release# builds garnotify and garnotifyctl

$sudo cp target/release/garnotify /usr/local/bin/

$sudo cp target/release/garnotifyctl /usr/local/bin/

Dependencies

gartk - gardesk UI toolkit for X11 rendering
cairo - 2D graphics library
pango - Text rendering with markup support
dbus - D-Bus session bus for FreeDesktop interface

Quick Start

Start the notification daemon and send a test notification.

Starting the Daemon

$garnotify daemon# start in background (default)

$garnotify daemon --foreground# start in foreground for debugging

Sending Test Notifications

$notify-send "Hello" "This is a test notification"

$notify-send -u critical "Alert" "Critical notification"

$notify-send -u low "Info" "Low priority notification"

Using garnotifyctl

$garnotifyctl status# check daemon status

$garnotifyctl count# get active notification count

$garnotifyctl list# list active notifications

$garnotifyctl close# close most recent notification

Autostart with gar

Add garnotify to your gar configuration to start automatically.

-- ~/.config/gar/init.lua
gar.exec_once("garnotify daemon")

systemd Service

Create a user service for automatic startup.

# ~/.config/systemd/user/garnotify.service
[Unit]
Description=garnotify notification daemon
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/garnotify daemon --foreground
Restart=on-failure

[Install]
WantedBy=graphical-session.target

$systemctl --user daemon-reload

$systemctl --user enable --now garnotify.service

Replace Existing Daemon

Only one notification daemon can claim the D-Bus name. Stop existing daemons first.

$pkill dunst# stop dunst if running

$pkill mako# stop mako if running

$garnotify daemon

Configuration Files

garnotify loads configuration from these locations in priority order:

Command-line --config path (if provided)
gar's Lua config: ~/.config/gar/init.lua (gar.notification table)
TOML config: ~/.config/garnotify/config.toml
Built-in defaults

Minimal Configuration

A minimal TOML configuration to get started:

# ~/.config/garnotify/config.toml

[geometry]
position = "top-right"
width = 350
offset_x = 20
offset_y = 40

[timeouts]
normal = 5000
critical = 0

Lua Configuration (gar Integration)

Configure garnotify within gar's init.lua for unified desktop setup:

-- ~/.config/gar/init.lua

gar.notification = {
  position = "top-right",
  width = 350,
  offset_x = 20,
  offset_y = 40,
  max_visible = 5,

  -- Timeouts
  timeouts = {
    low = 10000,
    normal = 5000,
    critical = 0,
  },

  -- Appearance
  font = "Sans 11",
  title_font = "Sans Bold 12",
  padding = 12,
  corner_radius = 8,

  -- Colors (Catppuccin-inspired)
  background = "#1e1e2e",
  foreground = "#cdd6f4",
  border = "#45475a",

  -- Animation
  animation = {
    enabled = true,
    fade_in = 150,
    fade_out = 150,
    slide = "down",
  },
}

Full TOML Reference

# ~/.config/garnotify/config.toml

[general]
monitor = "primary"
follow_mouse = false

[geometry]
position = "top-right"
width = 350
max_height = 150
offset_x = 20
offset_y = 40
gap = 10
max_visible = 5

[timeouts]
default = 5000
low = 10000
normal = 5000
critical = 0

[appearance]
font = "Sans 11"
title_font = "Sans Bold 12"
icon_size = 48
padding = 12
corner_radius = 8
border_width = 2
markup_enabled = true

[appearance.colors]
background = "#1e1e2e"
foreground = "#cdd6f4"
border = "#45475a"
low_background = "#1e1e2e"
low_foreground = "#6c7086"
low_border = "#45475a"
critical_background = "#f38ba8"
critical_foreground = "#1e1e2e"
critical_border = "#f38ba8"

[animation]
enabled = true
fade_in = 150
fade_out = 150
slide = "down"
slide_distance = 20

[history]
max_length = 100
persist = true

General Options

Option	Type	Default	Description
`monitor`	string	"primary"	Monitor to show notifications on: "primary", "mouse", or monitor name
`follow_mouse`	bool	false	Follow mouse cursor to determine which monitor to use

Geometry Options

Option	Type	Default	Description
`position`	string	"top-right"	Position anchor: top-right, top-left, top-center, bottom-right, bottom-left, bottom-center
`width`	u32	350	Notification popup width in pixels
`max_height`	u32	150	Maximum height per notification (0 = unlimited)
`offset_x`	i32	20	Horizontal offset from screen edge in pixels
`offset_y`	i32	40	Vertical offset from screen edge in pixels
`gap`	i32	10	Gap between stacked notifications in pixels
`max_visible`	u32	5	Maximum number of visible notifications (0 = unlimited)

Timeout Options

Option	Type	Default	Description
`default`	i32	5000	Default timeout in milliseconds (-1 = server default)
`low`	i32	10000	Timeout for low urgency notifications in milliseconds
`normal`	i32	5000	Timeout for normal urgency notifications in milliseconds
`critical`	i32	0	Timeout for critical notifications (0 = never expire)

Timeouts are in milliseconds. A timeout of 0 means the notification never expires automatically. A value of -1 means use the server default (5000ms).

Appearance Options

Option	Type	Default	Description
`font`	string	"Sans 11"	Body font specification in Pango format
`title_font`	string	"Sans Bold 12"	Title/summary font specification in Pango format
`icon_size`	u32	48	Icon size in pixels
`padding`	u32	12	Padding inside notification popup
`corner_radius`	u32	8	Corner radius for rounded popup corners
`border_width`	u32	2	Border width around popup
`markup_enabled`	bool	true	Enable Pango markup parsing in notification body

Color Options

Option	Type	Default	Description
`background`	color	"#1e1e2e"	Default background color
`foreground`	color	"#cdd6f4"	Default foreground (text) color
`border`	color	"#45475a"	Default border color
`low_background`	color	"#1e1e2e"	Low urgency background
`low_foreground`	color	"#6c7086"	Low urgency foreground (dimmed)
`low_border`	color	"#45475a"	Low urgency border
`critical_background`	color	"#f38ba8"	Critical urgency background (pink/red)
`critical_foreground`	color	"#1e1e2e"	Critical urgency foreground (dark)
`critical_border`	color	"#f38ba8"	Critical urgency border

Colors can be specified as hex (#RRGGBB or #RRGGBBAA), rgb(), rgba(), or named colors. Default colors follow a Catppuccin-inspired dark theme.

Animation Options

Option	Type	Default	Description
`enabled`	bool	true	Enable slide and fade animations
`fade_in`	u32	150	Fade-in duration in milliseconds
`fade_out`	u32	150	Fade-out duration in milliseconds
`slide`	string	"down"	Slide direction: up, down, left, right, none
`slide_distance`	u32	20	Slide distance in pixels

History Options

Option	Type	Default	Description
`max_length`	usize	100	Maximum notifications to keep in history
`persist`	bool	true	Persist history to disk between sessions

History is stored in ~/.local/share/garnotify/history.json when persistence is enabled.

Overview

garnotify is a FreeDesktop-compliant notification daemon that implements the Desktop Notifications Specification version 1.2. It serves as the standard notification handler for the gardesk desktop environment, receiving notifications from any application that uses the standard D-Bus notification interface.

Supported Capabilities

Option	Type	Default	Description
`actions`	-	-	Supports notification action buttons
`body`	-	-	Supports notification body text
`body-markup`	-	-	Supports Pango markup in body (b, i, u, etc.)
`body-hyperlinks`	-	-	Supports hyperlinks in body (rendered as underlined)
`icon-static`	-	-	Supports static notification icons
`persistence`	-	-	Supports notification history/persistence

Key Features

FreeDesktop Desktop Notifications Specification 1.2 compliance
Configurable popup positioning with 6 anchor points
Per-urgency timeout and color configuration
Powerful rule engine for filtering and modifying notifications
Persistent notification history with circular buffer
Do Not Disturb mode with multiple pause levels
Smooth slide and fade animations
Action button support with hover effects
IPC interface for external control and event subscriptions
Integration with gar's Lua configuration

Architecture

garnotify uses a multi-threaded architecture with async I/O. The main daemon thread handles D-Bus communication and IPC, while a dedicated UI thread manages X11 popup windows.

┌─────────────────────────────────────────────────────┐
│                   garnotify daemon                   │
├─────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌───────────────┐  ┌──────────┐ │
│  │  D-Bus       │  │  IPC Server   │  │  Rule    │ │
│  │  Service     │  │  (Unix sock)  │  │  Engine  │ │
│  └──────┬───────┘  └───────┬───────┘  └────┬─────┘ │
│         │                  │               │       │
│         ▼                  ▼               ▼       │
│  ┌────────────────────────────────────────────────┐│
│  │           Notification Store                   ││
│  │        (timeout management, events)            ││
│  └────────────────────────────────────────────────┘│
│                        │                           │
│         ┌──────────────┼──────────────┐           │
│         ▼              ▼              ▼           │
│  ┌───────────┐  ┌───────────┐  ┌───────────────┐ │
│  │  History  │  │  Event    │  │  UI Thread    │ │
│  │  (JSON)   │  │  Stream   │  │  (X11/Cairo)  │ │
│  └───────────┘  └───────────┘  └───────────────┘ │
└─────────────────────────────────────────────────────┘

D-Bus Service

garnotify registers the org.freedesktop.Notifications name on the session bus. It implements the standard methods:

GetCapabilities() - Returns supported features
Notify(...) - Send a notification, returns ID
CloseNotification(id) - Close notification by ID
GetServerInformation() - Returns name, vendor, version, spec version

And signals:

NotificationClosed(id, reason) - Emitted when notification closes
ActionInvoked(id, action_key) - Emitted when user clicks action button

Notification Store

The notification store manages active notifications with automatic timeout scheduling. When a notification is added:

If replaces_id > 0 and exists, the existing notification is replaced
A timeout task is spawned based on urgency-specific timeout settings
A Created or Updated event is emitted
The UI thread receives the event and shows/updates the popup

UI Thread

The UI thread runs separately from the async runtime to handle X11 event polling without blocking. It uses gartk for window management and Cairo for rendering. The thread runs at approximately 60fps (16ms poll interval) to ensure smooth animations.

Communication happens via channels: the daemon sends PopupCommands (Show, Update, Close, CloseAll) and receives PopupEvents (Dismissed, ActionInvoked, Closed).

Event Loop

The main event loop uses tokio's async runtime and handles:

D-Bus method calls and signal emissions
IPC commands from garnotifyctl
Notification events (created, closed, expired)
UI events (user dismissed, action clicked)
Unix signals (SIGTERM for shutdown, SIGHUP for reload)

Rule Engine

The rule engine allows filtering and modifying notifications based on pattern matching. Rules are processed in order - the first matching rule's actions are applied.

Rule Structure

Each rule has a name, match conditions, and actions to perform when matched.

# TOML rule example
[[rules]]
name = "mute-spotify"
enabled = true
match_app_name = "Spotify"
actions = [
  { type = "suppress" }
]

[[rules]]
name = "highlight-urgent-email"
match_app_name = "thunderbird"
match_summary = "*urgent*"
actions = [
  { type = "set_urgency", urgency = "critical" },
  { type = "prepend_summary", text = "[URGENT] " }
]

Match Options

Option	Type	Default	Description
`name`	string	-	Rule name for identification (required)
`enabled`	bool	true	Whether this rule is active
`match_app_name`	string?	-	Pattern to match against app_name field
`match_summary`	string?	-	Pattern to match against summary/title field
`match_body`	string?	-	Pattern to match against body text
`match_urgency`	string?	-	Pattern to match against urgency (low, normal, critical)

Pattern Syntax

Match patterns support three formats:

Simple string - Case-insensitive substring match
Glob pattern - * matches any characters, ? matches single character
Regex - Prefix with ~ for full regex support

# Simple: substring match (case-insensitive)
match_app_name = "firefox"      # matches "Firefox", "Mozilla Firefox"

# Glob: wildcards
match_summary = "*error*"       # matches "An error occurred"
match_app_name = "fire*"        # matches "Firefox", "Firewall"

# Regex: prefix with ~
match_body = "~\\d+ new messages"  # matches "5 new messages"
match_app_name = "~^(Firefox|Chrome)$"

Available Actions

Option	Type	Default	Description
`suppress`	-	-	Suppress the notification (do not show)
`set_urgency`	-	-	Set urgency level (requires "urgency" field: low, normal, critical)
`set_timeout`	-	-	Override timeout in milliseconds (requires "timeout" field)
`set_summary`	-	-	Replace summary text (requires "summary" field)
`set_body`	-	-	Replace body text (requires "body" field)
`append_body`	-	-	Append text to body (requires "text" field)
`prepend_summary`	-	-	Prepend text to summary (requires "text" field)
`set_sound`	-	-	Set notification sound (requires "sound" field)
`set_transient`	-	-	Mark as transient - skip history (requires "transient" field)
`exec`	-	-	Execute shell command with notification data as env vars (requires "command" field)

Action Examples

Suppress Notifications

[[rules]]
name = "mute-discord-typing"
match_app_name = "discord"
match_summary = "*typing*"
actions = [{ type = "suppress" }]

Override Timeout

[[rules]]
name = "long-email-timeout"
match_app_name = "thunderbird"
actions = [{ type = "set_timeout", timeout = 15000 }]

Modify Content

[[rules]]
name = "tag-slack"
match_app_name = "Slack"
actions = [
  { type = "prepend_summary", text = "[Slack] " },
  { type = "set_urgency", urgency = "normal" }
]

Execute Command

[[rules]]
name = "log-critical"
match_urgency = "critical"
actions = [
  { type = "exec", command = "logger -t garnotify 'Critical: $NOTIFICATION_SUMMARY'" }
]

The exec action provides environment variables: NOTIFICATION_ID, NOTIFICATION_APP, NOTIFICATION_SUMMARY, NOTIFICATION_BODY

Runtime Rule Control

Rules can be enabled or disabled at runtime without restarting the daemon.

$garnotifyctl rule-disable mute-spotify# disable rule

$garnotifyctl rule-enable mute-spotify# re-enable rule

$garnotifyctl reload# reload config (including rules)

IPC Protocol

garnotify provides an IPC interface via Unix domain socket for external control and event subscriptions. The socket is located at $XDG_RUNTIME_DIR/garnotify.sock.

CLI Options

Option	Type	Default	Description
`--foreground, -f`	-	false	Run daemon in foreground (useful for debugging)
`--config, -c`	-	~/.config/garnotify/config.toml	Path to configuration file

garnotifyctl Commands

Option	Type	Default	Description
`close [ID]`	-	-	Close notification by ID (omit ID to close most recent)
`close-all`	-	-	Close all visible notifications
`history-pop`	-	-	Pop and redisplay most recent notification from history
`history-clear`	-	-	Clear notification history
`set-paused <true\|false> [-l LEVEL]`	-	-	Set Do Not Disturb mode (level: 0=show all, 1=critical only, 2=show none)
`is-paused`	-	-	Check if DND is enabled (returns JSON with paused and level)
`count`	-	-	Get count of active notifications
`list [--json]`	-	-	List active notifications
`rule-enable <name>`	-	-	Enable a rule by name
`rule-disable <name>`	-	-	Disable a rule by name
`reload`	-	-	Reload configuration file
`status`	-	-	Get daemon status (running, counts, DND state)
`quit`	-	-	Stop the daemon

JSON Protocol

IPC uses newline-delimited JSON. Each command is a JSON object with a "command" field.

Available Commands

Option	Type	Default	Description
`close`	-	-	Close notification by ID or most recent if id is null
`close_all`	-	-	Close all visible notifications
`history_pop`	-	-	Pop and redisplay from history
`history_clear`	-	-	Clear notification history
`set_paused`	-	-	Set DND state (paused: bool, level: u8)
`is_paused`	-	-	Query DND state
`count`	-	-	Get active notification count
`list`	-	-	List active notifications
`rule_enable`	-	-	Enable rule by name
`rule_disable`	-	-	Disable rule by name
`reload`	-	-	Reload configuration
`status`	-	-	Get daemon status
`subscribe`	-	-	Subscribe to notification events (keeps connection open)
`quit`	-	-	Stop daemon

Command Examples

// Close notification by ID
{"command": "close", "id": 42}

// Close most recent
{"command": "close"}

// Close all
{"command": "close_all"}

// Set DND (critical only)
{"command": "set_paused", "paused": true, "level": 1}

// Query status
{"command": "status"}

// Enable/disable rule
{"command": "rule_enable", "name": "mute-spotify"}
{"command": "rule_disable", "name": "mute-spotify"}

Response Format

All commands return a JSON response:

// Success (no data)
{"success": true, "message": "Closed notification 42"}

// Success with data
{"success": true, "data": {"count": 3}}

// Error
{"success": false, "message": "Notification not found"}

// Status response
{
  "success": true,
  "data": {
    "running": true,
    "active_count": 2,
    "history_count": 15,
    "paused": false,
    "pause_level": 0
  }
}

Event Subscription

The subscribe command keeps the connection open and streams events as they occur. Useful for status bar integration.

Event Types

Option	Type	Default	Description
`notification_new`	-	-	New notification created (id, app_name, summary, body, urgency)
`notification_closed`	-	-	Notification closed (id, reason)
`notification_updated`	-	-	Notification updated/replaced (id, summary, body)
`paused_changed`	-	-	DND state changed (paused: bool)
`count_changed`	-	-	Active count changed (count: number)

Event Examples

// New notification
{"event": "notification_new", "id": 42, "app_name": "Firefox",
 "summary": "Download Complete", "body": "file.zip", "urgency": "Normal"}

// Notification closed
{"event": "notification_closed", "id": 42, "reason": "Dismissed"}

// DND changed
{"event": "paused_changed", "paused": true}

// Count changed
{"event": "count_changed", "count": 3}

Status Bar Integration

Example script for displaying notification count in a status bar:

#!/bin/bash
# garnotify-count.sh - for polybar, waybar, etc.

count=$(garnotifyctl count 2>/dev/null | jq -r '.count // 0')
paused=$(garnotifyctl is-paused 2>/dev/null | jq -r '.paused // false')

if [ "$paused" = "true" ]; then
  echo " DND"
elif [ "$count" -gt 0 ]; then
  echo " $count"
else
  echo ""
fi

Streaming Example

#!/bin/bash
# Stream events and update status

echo '{"command":"subscribe"}' | nc -U "$XDG_RUNTIME_DIR/garnotify.sock" | while read -r line; do
  event=$(echo "$line" | jq -r '.event // empty')
  case "$event" in
    count_changed)
      count=$(echo "$line" | jq -r '.count')
      echo "Notifications: $count"
      ;;
    paused_changed)
      paused=$(echo "$line" | jq -r '.paused')
      [ "$paused" = "true" ] && echo "DND enabled" || echo "DND disabled"
      ;;
  esac
done

Raw Socket Usage

$echo '{"command":"status"}' | nc -U $XDG_RUNTIME_DIR/garnotify.sock

$echo '{"command":"count"}' | nc -U $XDG_RUNTIME_DIR/garnotify.sock

$echo '{"command":"list"}' | nc -U $XDG_RUNTIME_DIR/garnotify.sock | jq

Common Issues

"Failed to request D-Bus name (is another notification daemon running?)"

Only one notification daemon can claim the D-Bus name. Stop existing daemons:

$pkill dunst

$pkill mako

$pkill notification-daemon

$garnotify daemon

"garnotify daemon already running"

A previous instance may have crashed. Clean up stale files:

$rm -f $XDG_RUNTIME_DIR/garnotify.pid

$rm -f $XDG_RUNTIME_DIR/garnotify.sock

$garnotify daemon

Notifications not appearing

Check if daemon is running and DND is disabled:

$garnotifyctl status# check daemon status

$garnotifyctl is-paused# check DND state

$garnotifyctl set-paused false# disable DND

Popups appear in wrong position

Check geometry configuration:

[geometry]
position = "top-right"  # or top-left, top-center, bottom-*
offset_x = 20
offset_y = 40
monitor = "primary"     # or specific monitor name

Rules not working

Verify rule syntax and check if enabled:

$garnotify daemon --foreground# run in foreground to see logs

$RUST_LOG=debug garnotify daemon --foreground# enable debug logging

Look for "Rule 'name' matched notification" or "Rule 'name' suppressed notification" messages.

Icons not displaying

garnotify looks for icons in standard locations. Ensure icon themes are installed:

$ls /usr/share/icons/# check available icon themes

$sudo dnf install adwaita-icon-theme# install default theme

History not persisting

Ensure persistence is enabled and the data directory exists:

[history]
persist = true
max_length = 100

$mkdir -p ~/.local/share/garnotify

$ls -la ~/.local/share/garnotify/# check for history.json

Debugging

Enable Debug Logging

$RUST_LOG=debug garnotify daemon --foreground

$RUST_LOG=garnotify=debug garnotify daemon --foreground# garnotify only

Test Notifications

$notify-send "Test" "Normal notification"

$notify-send -u low "Test" "Low urgency"

$notify-send -u critical "Test" "Critical urgency"

$notify-send -i firefox "Test" "With icon"

$notify-send "Test" "With action" --action="ok=OK"

Monitor D-Bus Traffic

$dbus-monitor "interface=org.freedesktop.Notifications"

Check Server Information

$gdbus call --session --dest org.freedesktop.Notifications --object-path /org/freedesktop/Notifications --method org.freedesktop.Notifications.GetServerInformation

$gdbus call --session --dest org.freedesktop.Notifications --object-path /org/freedesktop/Notifications --method org.freedesktop.Notifications.GetCapabilities

Log Locations

Console output when running with --foreground
systemd journal: journalctl --user -u garnotify
History file: ~/.local/share/garnotify/history.json

Getting Help

If you encounter issues not covered here:

Check the GitHub Issues
Run with debug logging and include relevant output
Include your configuration file when reporting issues

garnotify

Installation

Using DNF (Recommended)

Building from Source

Dependencies

Quick Start

Starting the Daemon

Sending Test Notifications

Using garnotifyctl

Autostart with gar

systemd Service

Replace Existing Daemon

Configuration Files

Minimal Configuration

Lua Configuration (gar Integration)

Full TOML Reference

General Options

Geometry Options

Timeout Options

Appearance Options

Color Options

Animation Options

History Options

Overview

Supported Capabilities

Key Features

Architecture

D-Bus Service

Notification Store

UI Thread

Event Loop

Notification Model

Notification Fields

Urgency Levels

Supported Hints

Action Buttons

Do Not Disturb

Pause Levels

Controlling DND

History

Persistence

Persistence

Transient Notifications

UI Rendering

gartk Integration

Animations

Popup Layout

Rule Engine

Rule Structure

Match Options

Pattern Syntax

Available Actions

Action Examples

Suppress Notifications

Override Timeout

Modify Content

Execute Command

Runtime Rule Control

IPC Protocol

CLI Options

garnotifyctl Commands

JSON Protocol

Available Commands

Command Examples

Response Format

Event Subscription

Event Types

Event Examples

Status Bar Integration

Streaming Example

Raw Socket Usage

Common Issues

"Failed to request D-Bus name (is another notification daemon running?)"

"garnotify daemon already running"

Notifications not appearing

Popups appear in wrong position

Rules not working

Icons not displaying

History not persisting

Debugging