znotify
A lightweight, cross-platform command-line utility for desktop notifications written in Zig.
Features
- Zero Dependencies: Single static binary with no runtime dependencies
- Cross-Platform: Works on Windows, Linux, and macOS
- Fast: <50ms notification display, <500KB binary size
- Privacy-First: No telemetry, no network calls, no data collection
- notify-send Compatible: Drop-in replacement for notify-send
Status
In Development - Not yet ready for production use
Currently implemented:
- Core notification data structures
- CLI argument parser with full option support
- Input validation and sanitization
- Error handling with user-friendly messages
- Performance benchmarks
- Docker-based testing infrastructure
- Platform abstraction layer
- Windows notifications (WinRT Toast API with direct COM implementation)
- Toast notifications with title and message
- Start Menu shortcut creation with AppUserModelID
- Urgency level mapping (duration, audio, and scenario attributes)
- Platform-specific duration control (--duration short|long)
- Direct COM calls for 17x performance improvement vs PowerShell
- Action Center integration
- Linux notifications (D-Bus implementation)
- D-Bus binary protocol implementation (zero dependencies)
- Basic notifications with title and message
- Urgency levels (low/normal/critical) with visual distinction
- Timeout handling (persistent, timed, or default)
- Icon support (theme names and file paths via -i option)
- Notification updates via replaces_id (-r option)
- Capability detection (GetCapabilities with helper functions)
- Action buttons (--action option, with daemon-specific behavior)
- ActionInvoked signal handler with --wait mode (blocks until user clicks action)
- Wait timeout support (--wait-timeout in milliseconds)
- Compatible with all notification daemons (Dunst, Mako, notify-osd, GNOME, KDE, XFCE)
- Note: Dunst required for visual action buttons; Mako uses CLI-based invocation
- macOS notifications
- Native notifications with title and message
- Requires macOS 10.14+ (Mojave or later)
- Notification Center integration
- Icon support (local file paths and builtin SF Symbols)
Coming soon:
- Urgency levels (macOS)
- Timeout control (macOS)
- Action buttons (macOS, Windows)
- Sound hints (Linux)
- Configuration file support
- Shell_NotifyIcon fallback (Windows 8.1)
Building
Requirements
- Zig 0.15.1 or higher
- Git 2.0+
Build Commands
# Build the project
zig build
# Run tests
zig build test
# Run benchmarks
zig build bench
# Build release binary
zig build -Doptimize=ReleaseSafe
Cross-Platform Builds
# Windows (x86_64)
zig build -Dtarget=x86_64-windows
# Linux (x86_64)
zig build -Dtarget=x86_64-linux-gnu
# macOS (x86_64)
zig build -Dtarget=x86_64-macos
# macOS (ARM64)
zig build -Dtarget=aarch64-macos
Docker Testing
Test Linux D-Bus functionality on any platform:
# Build Docker image
./scripts/build-docker.sh # Linux/macOS
.\scripts\build-docker.ps1 # Windows
# Run tests
./scripts/test-linux.sh test # Linux/macOS
.\scripts\test-linux.ps1 test # Windows
See docker/README.md for details.
Usage
# Basic notification
znotify "Title" "Message"
# With urgency level
znotify "Warning" "Disk space low" -u critical
# With icon
znotify "Update Available" "Click to install" -i software-update
# Custom timeout (Linux/macOS)
znotify "Auto-save" "Changes saved" -t 2000
# Windows duration control
znotify "Quick Alert" "Disappears in 5-10s" --duration short
# Action buttons with wait mode (Linux with Dunst)
znotify "Confirm" "Delete file?" \
--action "yes" "Yes" \
--action "no" "No" \
--wait \
--wait-timeout=30000
# Blocks until user clicks, prints: "Action invoked: yes"
# notify-send compatibility mode
znotify --compat -u low -i dialog-information "Info" "Operation complete"
Architecture
CLI Layer (cli.zig)
↓
Core Engine (core.zig, notification.zig)
↓
Platform Abstraction Layer (platform/backend.zig)
↓
Platform Implementations
├── Windows: WinRT Toast API
├── Linux: D-Bus (org.freedesktop.Notifications)
└── macOS: UserNotifications framework
Performance Targets
- Binary size: <500KB (target), <1MB (maximum)
- Startup time: <10ms (target), <50ms (maximum)
- Memory usage: <5MB (target), <10MB (maximum)
- Notification display: <50ms (target), <100ms (maximum)
Development
Running Tests
# Unit tests
zig build test
# Benchmarks
zig build bench
# Linux integration tests (Docker)
./scripts/test-linux.sh test # Linux/macOS
.\scripts\test-linux.ps1 test # Windows
License
MIT License - See LICENSE for details.