Modules Reference
Modules are larger UI surfaces beyond the bar, such as the dock, notifications, overview, and OSD. They are configured under [modules.<name>] in config.toml.
Unlike widgets, most modules are standalone windows or overlays that need to be explicitly enabled.
The bar itself is a module. Configures position, layer, auto-hide behavior.
[modules.bar]layer = "top" # "top" | "overlay" | "bottom" | "background"auto_hide = falseauto_hide_timeout = 3000 # millisecondslocation = "top" # "top" | "bottom"exclusive = truelayer: Hyprland layer —toprenders above windows,backgroundrenders below.auto_hide: Hides the bar after the timeout when not hovered.location: Bar position on screen.exclusive: Reserves screen space for the bar. Setfalseto let windows overlap it, useful withauto_hide.
Notification System
Section titled “Notification System”Displays desktop notifications as they arrive, with stacking, grouping, and Do Not Disturb.
[modules.notification]enabled = trueanchor = "top-right"layer = "overlay" # "top" | "overlay" | "bottom" | "background"auto_dismiss = truerespect_expire = truednd_on_screencast = trueignored = []transition_type = "slide-left" # "slide-left" | "slide-right" | "slide-up" | "slide-down" | "crossfade"transition_duration = 350per_app_limits = {}play_sound = falsemax_actions = 3copy_code_action = trueshow_timestamp = truedismiss_on_hover = falsesound_file = "notification4"max_lines = 4max_expanded_lines = 20
[modules.notification.timeout]low = 3000normal = 8000critical = 15000
[modules.notification.persist]enabled = truelow = truenormal = truecritical = truemax_count = 200anchor: Screen position for the notification window.layer: Hyprland layer for the notification popup.auto_dismiss: Automatically dismiss notifications after their timeout.respect_expire: Whether to respect the expire timeout from the notification sender.dnd_on_screencast: Enables Do Not Disturb mode during screen recording.per_app_limits: Limit notifications per application:{ "app_name": 5 }.copy_code_action: Detects one-time (2FA) codes in the body and shows aCopy "123456"action that copies the code to the clipboard and dismisses the notification.show_timestamp: Shows a relative timestamp (e.g.5m ago) in the notification header.persist: Save notifications to disk for recall after restart.
A pinned-application launcher with intellihide, window previews, and app grouping.
[modules.dock]enabled = falseignored = []icon_size = 40behavior = "intellihide" # "intellihide" | "always_show"tooltip = falselayer = "top"show_when_no_windows = falsegroup_apps = truetruncation_size = 20orientation = "horizontal"always_show_focused = truehide_special_workspace_apps = falseshow_launcher = truelauncher_position = "last" # "first" | "last"ignored = []behavior:intellihidehides the dock when a window overlaps it;always_showkeeps it visible.s: Shows window preview thumbnails on hover.group_apps: Groups multiple windows from the same application.show_launcher: Adds an application launcher icon to the dock.hide_special_workspace_apps: Hides apps on special workspaces (scratchpads).
Keybindings
Section titled “Keybindings”Navigate the dock with:
| Action | Keybinding |
|---|---|
| Focus next client | Super+Tab |
| Focus previous client | Super+Shift+Tab |
| Open launcher | Super+Space |
| Move client to workspace | Right-click → “Move to Workspace” |
Overview (Workspace Exposé)
Section titled “Overview (Workspace Exposé)”Full-screen overview of all workspaces and their windows.
[modules.overview]enabled = falselayer = "top"anchor = "center"transition_type = "crossfade" # "crossfade" | "slide-left" | "slide-right" | "slide-up" | "slide-down"transition_duration = 350Opens with a configurable keybinding (default: Super+W). Shows workspace thumbnails with click-to-focus.
Launcher
Section titled “Launcher”Keyboard-driven application launcher with search, grid/list layout, and drag-to-pin.
[modules.launcher]enabled = falsetooltip = trueicon_size = 35ignored = []anchor = "center"width = 280height = 320layout = "grid" # "grid" | "list"grid_columns = 3grid_spacing = 12plugins_enabled = true # slash-command plugins (/calc, /translate)plugins_dir = "" # default: <config>/pluginsplugins = ["calc", "emoji"] # allowlist of plugins to load (empty = none)layout:gridshows app icons in a grid;listshows them as a list with names.anchor: Position on screen (center,top,bottom, etc.).ignored: List of desktop file names to exclude from search results.plugins_enabled: Enables slash-command plugins (/calc,/translate, …).plugins_dir: Directory containing Python plugins; defaults to<config>/plugins.plugins: Strict allowlist of plugin names to load (e.g.["calc", "emoji"]). An empty list loads no plugins — list every plugin you want to use. Names are matched case-insensitively against the plugin’sname(the slash command), not its aliases.
Keybindings
Section titled “Keybindings”| Action | Keybinding |
|---|---|
| Open launcher | Super+Space |
| Navigate | Arrow keys |
| Launch app | Enter |
| Close | Escape |
Slash Commands & Plugins
Section titled “Slash Commands & Plugins”Type / in the search box to browse the available slash commands, or use one
straight away, e.g. /calc 2+2 or /translate bonjour. Only plugins listed
under plugins in [modules.launcher] are loaded — an empty list means no
slash commands are available. Plugins are written in Python — drop a .py
file (or a package directory) into plugins/, add its name to plugins,
and restart the bar.
Bundled plugins:
/calc— math, units and currency via libqalculate (qalc), e.g./calc 100 cm to inches./translate— translation with auto-detected source language, e.g./translate bonjour./emoji— offline emoji search, e.g./emoji rocket./clipboard-history— searchcliphisthistory and copy an item back, e.g./clipboard-history https://./currency— convert between currencies with live rates (Frankfurter, no API key), e.g./currency 100 usd to eur./kill— search running processes and kill the selected one (SIGTERM, or SIGKILL with-9), e.g./kill firefox. A numeric query is treated as a port —/kill 3000kills whatever is listening on port 3000./search— search the web (DuckDuckGo, no API key) and open a result in your browser while copying its URL to the clipboard, e.g./search fabric hyprland./history— search your shell command history (bash, zsh, fish) and copy a command back to the clipboard, e.g./history git. Nothing is ever executed./define— look up a word on dict.org’s WordNet (DICT protocol, no API key), e.g./define serendipity; pick another database with/define -d foldoc monad./shorten— shorten a URL via is.gd (TinyURL fallback), e.g./shorten github.com/rubiin/tsumiki— Enter copies the short link./unicode— search and copy Unicode characters by name, e.g./unicode arrowor/unicode copyright.
Keyboard: Up/Down move the selection, Enter activates the highlighted
row, Escape closes.
Writing a plugin
Section titled “Writing a plugin”Each plugin subclasses LauncherPlugin:
from utils.plugin_manager import LauncherPlugin, PluginResult, copy_to_clipboard
class HelloPlugin(LauncherPlugin): name = "hello" # slash command: /hello description = "Say hello" icon = "face-smile-symbolic" aliases = ["hi"]
def handle(self, args): # Runs on a worker thread - no GTK calls allowed here. who = args.strip() or "world" return [PluginResult(f"Hello, {who}!", subtitle="Press Enter to copy")]
def execute(self, result): if result: copy_to_clipboard(result.title) return False # False closes the launchernameis the slash command;aliasesregisters additional names.handle(args)returns the rows shown live while you type.execute(result)runs when a row is activated (Enter/click); returnTrueto keep the launcher open.handle()runs on a worker thread — keep it free of GTK calls. Broken plugins are skipped with a warning and never crash the bar.- For multi-file plugins, use a package (a directory with
__init__.py) and re-export the plugin class from__init__.py.
For the full plugin API — class attributes, helpers, cancellation, debouncing, and package layout — see the Plugin Development guide.
OSD (On-Screen Display)
Section titled “OSD (On-Screen Display)”Transient overlays for volume, brightness, and other adjustments.
[modules.osd]enabled = falsetimeout = 1500anchor = "bottom-center"layer = "overlay" # "top" | "overlay" | "bottom" | "background"orientation = "horizontal"style = "default" # "default" | "compact" | "bar" | "minimal"percentage = trueicon_size = 28transition_type = "slide-up" # "slide-up" | "slide-down" | "slide-left" | "slide-right" | "crossfade"transition_duration = 500osds = ["brightness", "volume"]osds: Which OSD types to show. Available:brightness,volume,microphone,lockkeys.layer: Hyprland layer for the OSD window.percentage: Shows a percentage indicator alongside the icon.style: Structural style of the OSD:defaultshows icon, slider and percentage,compactdrops the slider,bardrops the icon,minimalremoves the box background.
Desktop Clock
Section titled “Desktop Clock”A decorative clock overlay on the desktop (layer bottom).
[modules.desktop_clock]enabled = falsetype = "cookie" # Clock widget typelayer = "bottom"anchor = "bottom-right"date_format = "%A, %d %B %Y"time_format = "%H:%M"cookie_size = 230cookie_sides = 9cookie_dial_style = "dots"cookie_hour_hand_style = "fill"cookie_minute_hand_style = "medium"cookie_second_hand_style = "dot"cookie_date_style = "bubble"cookie_show_seconds = falsecookie_show_hour_marks = falsecookie_background_opacity = 1.0cookie_widget_scale = 1.0The cookie_* options configure the visual style of the analog clock widget.
Desktop Quotes
Section titled “Desktop Quotes”Displays rotating inspirational quotes on the desktop.
[modules.desktop_quotes]enabled = falseanchor = "bottom-right"layer = "bottom"interval = 600 # Seconds between quote rotationsQuotes are fetched from an external API.
Desktop Notes
Section titled “Desktop Notes”Sticky notes on the desktop. Right-click the desktop and pick New note to
add one, drag it by its top strip, type straight into it, and click the dot to
cycle its colour. Notes are saved to desktop_notes.json in the Tsumiki data
directory, per monitor, and restored on restart.
[modules.desktop_notes]enabled = falselayer = "bottom"note_width = 240 # Width of each note in pixelssave_delay = 800 # Milliseconds to wait after an edit before writing to disktooltip = true # Show tooltips on note buttonsThe full-screen window takes mouse clicks for the desktop, so it should stay on
the bottom layer; use the close (×) button on a note to delete it. Set
tooltip = false, or the global general.tooltips = false, to hide the hints
on the note buttons.
Activate Linux
Section titled “Activate Linux”Shows a window activation hint overlay (similar to GNOME’s window overview on Alt+Tab).
[modules.activate_linux]enabled = falseanchor = "bottom-right"layer = "bottom"Screen Corners
Section titled “Screen Corners”Adds hot corners to the screen edges.
[modules.screen_corners]enabled = falsesize = 20Cheatsheet
Section titled “Cheatsheet”A searchable Hyprland keybinding cheatsheet.
Configured under [widgets.cheatsheet] — see the Widgets Reference for details.
Settings GUI
Section titled “Settings GUI”An in-app GUI for editing Tsumiki configuration.
Triggered from the Settings widget ([widgets.settings]). No module-level configuration needed.