commit - a08809ec69ae6dd0ca37a31535b8a0a3405883e5
commit + f5a66e22aad9ed70c7ab678ffce9d461de4c5ef2
blob - /dev/null
blob + b8f255dd8f977ad1b4601febec24e7bf8907145e (mode 644)
--- /dev/null
+++ LICENSE.md
+# LICENSE
+
+[ISC License](https://opensource.org/licenses/ISC)
+
+Copyright (c) 2026 Brett Fisher <code@brettfisher.xyz>
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted, provided that the
+above copyright notice and this permission notice appear in all
+copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
+OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
blob - /dev/null
blob + 5cc5c3bf3826bb736024de6164f49ec6f8094ecb (mode 644)
--- /dev/null
+++ README.md
+# bxnotify
+
+A very basic X notification tool.
+
+## Just a Heads-Up
+
+I needed a way to display a short message on screen from a shell
+script or a Lua program. I did not need a notification daemon, a
+dbus service, or a background process. I just needed a small
+program that reads text from stdin and shows it.
+
+bxnotify is the result: a one-shot notification renderer. Each
+invocation displays a single notification, then exits. Concurrent
+invocations stack vertically, so multiple notifications can be
+visible at once.
+
+## Dependencies
+
+- Xlib
+- Xft
+- A C compiler compliant with the C11 standard.
+
+## Build
+
+Compile __bxnotify__ from source.
+
+```
+make
+```
+
+
+## Install
+
+Install the binary and man page. Note that root privileges are not
+required as the default destination is `~/.local/`.
+
+```
+make install
+```
+
+
+## Uninstall
+
+Remove the binary and man page.
+
+```
+make uninstall
+```
+
+
+## Configuration
+
+__bxnotify__ is configured at compile-time by editing config.def.h.
+After making changes, the program must be recompiled and
+reinstalled. See bxnotify(1) for details.
+
+Command line flags override configuration defaults for font,
+colors, alignment, and duration.
+
+## Design & Functionality
+
+__bxnotify__ is built around a set of opinionated primitives:
+
+- One-shot renderer: reads from stdin, shows a notification, exits
+- Concurrent notifications stack vertically
+- Auto-sized height based on the number of input lines
+- Word wraps long lines to fit the configured width
+- Dismissed with Mod4+q (sends SIGUSR1 to the owning process)
+- Configurable duration in seconds (0 = persist until dismissed)
+- Runtime registry at `~/.local/tmp/bxnotify.reg` for stacking,
+ coordinated with flock(2) and pruned with kill(2)
+
+## Usage
+
+Send a notification from the shell.
+
+```
+echo “Notify me about this” | bxnotify
+```
+
+Send a multi-line notification.
+
+```
+printf “Notify me about this\nNotify me about that” | bxnotify
+```
+
+Send a notification with a custom duration.
+
+```
+echo “Notify me for a long time” | bxnotify -d 30
+```
+
+Send a notification from a Lua script.
+
+```
+os.execute("echo 'Notify me about this' | bxnotify")
+```
+
+When used with bxwm(1) and bxbar(1), bxnotify complements the
+suite by providing visual feedback for system events and scripts
+without requiring dbus or a notification daemon.
+
blob - /dev/null
blob + a0711aa0b60a286a5659e9a8fd75c182e05ecd50 (mode 644)
--- /dev/null
+++ bxnotify.1
+.Dd June 18, 2026
+.Dt BXNOTIFY 1
+.Os
+.Sh NAME
+.Nm bxnotify
+.Nd basic X notification tool
+.Sh SYNOPSIS
+.Nm
+.Op Fl d Ar duration
+.Op Fl f Ar font
+.Op Fl F Ar foreground
+.Op Fl B Ar background
+.Op Fl C Ar border
+.Op Fl a Ar alignment
+.Sh DESCRIPTION
+.Nm
+is a notification tool for the X11 window system that reads text
+from standard input and displays it as a transient pop-up window
+at the top right of the screen.
+.Nm
+is a one-shot renderer: each invocation displays a single
+notification, then exits after the configured duration or when
+dismissed by the user. Concurrent invocations of
+.Nm
+stack vertically on screen, with new notifications appearing
+below existing ones.
+.Sh OPERATION
+.Nm
+manages notifications in the following manner:
+.Bl -tag -width indent
+.It Sy Input Processing
+.Nm
+reads lines from standard input using
+.Xr getline 3 .
+Lines longer than the configured width are word-wrapped. If no
+input is received, the program exits with an error.
+.It Sy Window Placement
+The notification window is created as an override-redirect
+window positioned at the top right of the screen, offset from the
+right edge by
+.Dv WIN_X
+pixels.
+.It Sy Stacking
+Concurrent notifications are stacked vertically.
+.Nm
+maintains a registry of active instances at
+.Pa ~/.local/tmp/bxnotify.reg ,
+using
+.Xr flock 2
+to coordinate concurrent access. Each instance records its PID,
+Y position, and height. Dead processes are detected and pruned
+with
+.Xr kill 2 .
+.It Sy Duration
+Notifications persist for
+.Dv DURATION
+seconds. A duration of 0 causes the notification to persist until
+dismissed.
+.It Sy Dismissal
+The oldest visible notification can be dismissed by pressing
+Mod4+q. If the press is received by a different instance of
+.Nm ,
+that instance sends
+.Dv SIGUSR1
+to the owning process, which exits gracefully.
+.El
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl d Ar duration
+Set the duration in seconds before the notification expires. A
+value of 0 means the notification persists until dismissed.
+.It Fl f Ar font
+Set the Xft font description string.
+.It Fl F Ar foreground
+Set the foreground (text) color, as an X color name or hex string.
+.It Fl B Ar background
+Set the background color, as an X color name or hex string.
+.It Fl C Ar border
+Set the border color, as an X color name or hex string.
+.It Fl a Ar alignment
+Set text alignment: 0 = left, 1 = center, 2 = right.
+.El
+.Sh CONFIGURATION
+.Nm
+is configured at compile-time by modifying the
+.Pa config.def.h
+header file.
+After modifying this file,
+.Nm
+must be recompiled and reinstalled to apply changes.
+The configuration file defines the default window width, screen
+offset, padding, border width, colors, font, alignment, and
+duration.
+.Sh FILES
+.Bl -tag -width ".Pa ~/.local/tmp/bxnotify.reg" -compact
+.It Pa config.def.h
+The default configuration file (see CONFIGURATION).
+.It Pa ~/.local/tmp/bxnotify.reg
+The runtime registry used to coordinate stacking of concurrent
+notifications.
+.El
+.Sh SEE ALSO
+.Xr bxwm 1 ,
+.Xr bxhkd 1 ,
+.Xr bxbar 1 ,
+.Xr X 7
+.Sh AUTHOR
+.An "Brett Fisher <code@brettfisher.xyz>."
+
