sxalert: scriptable, customizable, daemonless notifications

Three or so years ago I decided to write a simple notification tool in C so that I could easily script my notifications in Shell. After all this time of personal exclusive use, and a good refurbishment, I believe sxalert is ready for public use. Today I release version 1.0 of the tool!

sxalert is a GPLv3+ licensed minimal alert utility for X11 that supports freetype scalable fonts, utf-8 text, runtime customization of colors and border-width, multiple monitors and concurrent notification serialization. And all of this in a C file with less than 400 CLOC and very few dependencies! (though herbe beats me in that regard)

But perhaps most importantly, sxalert is scriptable. It accepts text from both command-line arguments and standard input. In fact, it can combine both sources so that the command-line argument text is appended to stdin text. This makes it great for displaying ASCII art banners directly from files with custom text added below. Moreover, mouse clicks result in distinct exit statuses (0 for left click, 1 for middle, 2 for right, and 3 incase of a timeout). This means that it can launch software, act as a dialogue box, and automate all sorts of tasks just based on your mouse input!

A few examples

Print a low-battery warning:

[ "$(cat /sys/class/power_supply/BAT0/capacity)" -lt 15 ] && sxalert "Battery below 15%"

Tell you if your build failed or not:

make && sxalert -t 55ff55 "Build successful" || sxalert -t ff5555 "Build failed"

Email notification that can launch neomutt in st:

sxalert -d 10000 "You have new mail" "Left click to read"; [ $? -eq 0 ] && st -e neomutt

and so much more:

cowsay you suck | sxalert -s

Customizability

sxalert allows for the runtime customization of text color, background color, border color and border width. You can configure duration in milliseconds (with values <= 0 being indefinite). From the config.h file, you can configure text height, font, position, size limitations and defaults for the colors and border width.

Any limitations?

Yes, sxalert doesn't support font-fallback, though this is planned for some time in the future. Likewise, it doesn't support markup or images and never will.

How to install

You can get the official v1.0 release tarball from here. Alternatively, you can clone the repository directly. I'll show you the former way:

$ wget https://mcdim.xyz/library/dist/sxalert-1.0.tar.gz
$ tar -xvf sxalert-1.0.tar.gz
$ cd sxalert-1.0/

There you can configure config.h as you like, and install with:

$ make
$ sudo make install

Consult on the manpage on usage!

Extras

Xresources patch

I also wrote a small patch for those who want their default notifications to be based on their xresources file. Apply it like so while in the project directory, ideally before editing any configuration code:

$ wget https://mcdim.xyz/library/dist/patches/sxalert-1.0-xresources.diff
$ patch < sxalert-1.0-xresources.diff

D-Bus daemon: Tiramisu integration

sxalert is easily integrated with the drawer-agnostic D-Bus daemon tiramisu. Simply install tiramisu and run this as a daemon script or directly in your .xinitrc:

tiramisu -o '#summary' | while IFS= read -r message; do
	sxalert -d 3000 "$message" </dev/null
done

Optional daemon hack

Back in 2023 I haphazardly hacked together a script called sxalertd that is essentially a pseudo daemon that intercepts D-Bus messages and uses sxalert to display them as notifications. It has worked fine for 3 years for me, and I've only used sxalert during this time. You can clone it from the repo.

Contributions

If you have any issues, or want to contribute patches, email <hackers@mcdim.xyz>. The repository on GitHub is a read-only mirror.

Enjoy!