histui

module

v0.0.14 Latest Latest Go to latest Published: Jul 11, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jmylchreest/histui

Links

Open Source Insights

README ¶

histui

A highly themeable GTK4 notification daemon for Wayland with persistent history.

histui displays desktop notifications with full CSS theming support, stores them for later browsing, and includes a TUI and CLI for querying your notification history.

Documentation | Releases

Features

Notification Daemon (histuid)

Fully themeable - Create your own themes with CSS, custom layouts, icons, and sounds
Theme packs - Self-contained themes with styling, layout, and audio in one directory
Hot reload - Edit themes live without restarting
Bundled themes - Includes default, minimal, compact, detailed, and catppuccin
Light/dark mode - Automatic switching based on system preference
Smart icons - App aliases with Nerd Font fallbacks for 350+ apps
Clickable notifications - URLs and deep links open the source app
Audio alerts - Per-urgency sounds with customizable audio files
Wayland native - Layer-shell support for Hyprland, Sway, river, and more

History & CLI (histui)

Persistent history - Notifications saved to SQLite across sessions
TUI browser - Navigate history with vim-style keybindings
Powerful filtering - Query by app, urgency, time range, regex
Pipeline friendly - JSON, dmenu, and ID output formats
Waybar integration - Real-time notification counts

Flexible Deployment

Standalone daemon - Replace dunst/mako entirely
Monitor mode - Keep your existing daemon, just add history tracking
Adapter system - Import history from dunst, mako, or swaync

Quick Start

# Install (Arch Linux)
yay -S histui-bin

# Start the notification daemon
systemctl --user enable --now histuid

# Browse your history
histui

Theming

Create custom themes with CSS and optional layout/audio:

~/.config/histui/themes/mytheme/
├── theme.css        # CSS styling
├── layout.xml       # Widget layout (optional)
├── manifest.toml    # Metadata and audio (optional)
└── sounds/          # Audio files (optional)

Or extend existing themes:

/* ~/.config/histui/themes/my-colors/theme.css */
@import "catppuccin.css";

.notification-popup {
    background-color: #1e1e2e;
    border-radius: 16px;
}

See the Theming Guide for full documentation.

CLI Examples

# List recent notifications
histui get

# Filter by app and time
histui get --filter "app=discord,timestamp>1h"

# Fuzzel picker
histui get | fuzzel -d | cut -d'|' -f1 | xargs histui get --field body | wl-copy

# Dismiss all Slack notifications
histui get --filter "app=slack" --format ids | histui set --stdin --dismiss

Waybar Integration

"custom/notifications": {
  "exec": "histui status --all --since 24h",
  "interval": 5,
  "return-type": "json",
  "on-click-middle": "hyprctl dispatch exec '[float;size 900 600;center] kitty -e histui'"
}

Configuration

Daemon config: ~/.config/histui/histuid.toml
CLI config: ~/.config/histui/config.toml
Themes: ~/.config/histui/themes/
History: ~/.local/share/histui/history.db

License

MIT License - see LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
histui command Package main is the entrypoint for histui CLI.	Package main is the entrypoint for histui CLI.
histuid command Package main is the entry point for the histuid notification daemon.	Package main is the entry point for the histuid notification daemon.
testnotify command testnotify - Send test notifications for histuid development	testnotify - Send test notifications for histuid development
embed Package embed provides embedded assets for histui.	Package embed provides embedded assets for histui.
internal
adapter/input Package input provides input adapters for notification sources.	Package input provides input adapters for notification sources.
adapter/output Package output provides output formatters for notifications.	Package output provides output formatters for notifications.
audio Package audio provides notification sound playback functionality.	Package audio provides notification sound playback functionality.
config Package config handles configuration file loading and parsing.	Package config handles configuration file loading and parsing.
core Package core provides filtering, sorting, and lookup logic.	Package core provides filtering, sorting, and lookup logic.
daemon Package daemon provides the main orchestration for histuid.	Package daemon provides the main orchestration for histuid.
db Package db provides SQLite-based storage for histui notifications.	Package db provides SQLite-based storage for histui notifications.
dbus Package dbus provides D-Bus interfaces for histui.	Package dbus provides D-Bus interfaces for histui.
display Package display manages GTK4/libadwaita popup windows for notifications.	Package display manages GTK4/libadwaita popup windows for notifications.
fswatcher Package fswatcher provides a generic file watcher built on fsnotify.	Package fswatcher provides a generic file watcher built on fsnotify.
icon Package icon provides icon name resolution and font loading.	Package icon provides icon name resolution and font loading.
layout
model Package model defines the core data structures for histui.	Package model defines the core data structures for histui.
theme Package theme handles CSS theme loading and hot-reload for histuid.	Package theme handles CSS theme loading and hot-reload for histuid.
tui Package tui provides image conversion utilities for terminal rendering.	Package tui provides image conversion utilities for terminal rendering.
types Package types provides shared custom types for configuration parsing.	Package types provides shared custom types for configuration parsing.