beeep

beeep is a small Go library for triggering desktop notifications, modal alerts, and PC-speaker beeps from within a Go program, without shelling out to a platform-specific SDK yourself. It exposes three functions - Notify, Alert, and Beep - that behave consistently across Linux, macOS, Windows, and WebAssembly builds, so the same call site works whether the binary ships to a Linux desktop, a Mac, or runs in a browser tab.

Under each function beeep layers OS-native backends with automatic fallbacks: Linux tries D-Bus first, then notify-send, then kdialog; macOS tries terminal-notifier before falling back to AppleScript’s osascript; Windows 10/11 uses the Windows Runtime toast API with a PowerShell fallback, while Windows 7 uses the legacy win32 balloon API. Icons can be passed as a file path or raw PNG bytes, and beeep handles the format conversion (PNG to ICO on Windows, PNG to ICNS on macOS) internally.

What You Get

• A single Notify(title, message, icon) call that works identically on Linux, macOS, Windows, and WebAssembly
• Automatic backend fallback chains per OS (D-Bus to notify-send to kdialog on Linux; terminal-notifier to osascript on macOS; toast API to PowerShell to win32 balloon on Windows)
• Built-in icon format conversion (PNG to ICO for Windows toasts, PNG to ICNS for macOS terminal-notifier) so you only ever supply a PNG
• A Beep(freq, duration) function that drives the PC speaker directly on Linux/Windows or falls back to a bell character/AppleScript beep
• A nodbus build tag to drop the godbus/dbus dependency entirely when only notify-send support is needed

Common Use Cases

• CLI tools that need to alert the user when a long-running build, download, or backup finishes
• Desktop utilities that surface background job status without building a full GUI
• Cross-platform Go apps that need one notification code path instead of per-OS branches
• Terminal/TUI programs that want an audible beep or bell on error or completion

Under The Hood

Architecture beeep ships as a single flat package with no subpackages, selecting its implementation at compile time via Go build tags rather than runtime dispatch (files suffixed _darwin.go, _windows.go, _unix.go, _js.go, and _unsupported.go each implement the same Notify/Alert/Beep surface independently). Shared helpers like pathAbs and bytesToFilename live in beeep.go; each platform file implements its own private fallback chain as a sequence of closures (e.g. dbus1, cmd1, cmd2 on Linux) tried in order and combined into a single wrapped error if all fail. The only exported state is a small set of package-level variables (AppName, an internal timeout), so there is no dependency injection or interface abstraction - the public surface is deliberately just three functions, appropriate for the library’s narrow scope but leaving package-level mutable state as the one rough edge.

Tech Stack Written in Go 1.21, with no web, ORM, or CLI framework since it is an OS-binding library rather than an application. Platform-specific dependencies do the heavy lifting: git.sr.ht/~jackmordaunt/go-toast for Windows 10/11 toast notifications, github.com/esiqveland/notify plus github.com/godbus/dbus/v5 for Linux D-Bus notifications, github.com/jackmordaunt/icns/v3 for macOS icon conversion, github.com/sergeymakinen/go-ico and go-bmp for Windows icon conversion, github.com/tadvi/systray for the Windows 7 balloon/tray fallback, and golang.org/x/sys for registry access used to detect the Windows version. CI runs via a GitHub Actions build workflow; the project ships as a library only, with no binary of its own beyond its test suite.

Code Quality Test files exist for each entry point (alert_test.go, beep_test.go, notify_test.go, example_test.go), but they are thin - each asserts only that the call did not return an error, and running them actually fires a real OS notification or beep rather than mocking exec.Command or the D-Bus connection. There are no table-driven tests and no visible coverage tracking. Error handling is explicit and consistently wrapped with %w through each platform’s multi-backend fallback chain, with clear naming conventions (notify1, cmd1/cmd2, dbus1) repeated across files. No dedicated linter configuration is visible beyond what the CI build step implies.

What Makes It Unique The library’s most polished idea is its per-OS layered fallback strategy - trying the richest available backend first and stepping down to simpler ones automatically within a single function call - which spares callers from writing their own platform-detection and retry logic. The underlying goal of cross-platform desktop notifications from Go is well-trodden territory with comparable prior art, so the value here is in the tidy, self-contained execution rather than a genuinely new technical approach.