GZML Visual Tools is a lightweight system tray application for Hyprland that provides quick access to visual customization features without requiring users to constantly edit configuration files.
The project was originally built for my own desktop workflow but has since grown into a modular customization toolkit focused on Hyprland's modern Lua configuration system.
Using the tray menu, users can:
- Switch animation presets
- Apply wallpaper effects
- Adjust blur intensity
- Adjust border sizes
- Import custom presets
- Reload Hyprland
- Manage visual settings from a single location
Most functionality is handled through small, readable scripts that can easily be modified or expanded by users.
The long-term goal is to provide a centralized visual management utility for Hyprland while remaining lightweight, modular, and easy to customize.
Many Hyprland users enjoy tweaking their desktops, but even simple changes often require:
-
Editing configuration files
-
Reloading Hyprland
-
Remembering configuration syntax
-
Searching through multiple folders
GZML Visual Tools reduces that friction by exposing commonly modified visual settings through an easy-to-access tray interface.
Instead of editing configuration files every time you want to experiment, most actions can be performed directly from the tray.
Load and switch between Hyprland animation presets directly from the tray.
- Active preset checkmark support
- One-click Hyprland reload
- Lua preset support
- Easy preset expansion
- Now comes pre-loaded with a bunch of animations!
Apply ImageMagick or awww powered wallpaper effects directly from the tray!
Current effects include:
- Black & White
- Charcoal
- Edge Detect
- Emboss
- Frame Raised
- Frame Sunk
- Negate
- Oil Paint
- Posterize
- Polaroid
- Sepia Tone
- Sharpen
- Solarize
- Vignette
- Vignette Black
- Zoomed
Wallpaper effects are self-contained scripts and can easily be modified, replaced, or expanded by users.
Wallpaper effects default to Noctalia Shell.
Each wallpaper effect script contains handler lines similar to:
# Noctalia / Quickshell
qs -p "$QS_DIR" ipc call wallpaper set "$wallpaper_output" "$focused_monitor"
# AWWW
# awww img --outputs "$focused_monitor" "$wallpaper_output"If you use AWWW instead of Noctalia:
- Comment out the Noctalia line.
- Uncomment the AWWW line.
This keeps wallpaper effects portable across different Hyprland setups.
Control Hyprland blur levels directly from the tray.
Available levels:
Off
Level 1 - Level 10
### 🔲 Border Controls
Adjust Hyprland border size without manually editing configuration files.
1px - 10px
Import custom presets directly from the tray.
Supports:
- Animations
- Wallpaper Effects
- Themes
- Tools
- Python 3
- python-gobject
- GTK3
- AppIndicator3
- Hyprland
- ImageMagick
- wallust
- jq
- Noctalia Shell
- AWWW
- GZML Shell
GZML Visual Tools was designed around the newer Hyprland Lua configuration system.
To enable Blur and Animation Controls, add the following lines at the end your normal decoration configuration file/s(place both in both files if seperate animation and decoration files exsist). Example:
Animations:
dofile(os.getenv("HOME") .. "/.config/gzml-visual-tools/hypr/animations.lua")
dofile(os.getenv("HOME") .. "/.config/gzml-visual-tools/hypr/blur.lua")
Decorations:
dofile(os.getenv("HOME") .. "/.config/gzml-visual-tools/hypr/animations.lua")
dofile(os.getenv("HOME") .. "/.config/gzml-visual-tools/hypr/blur.lua")
Place both at the end of the above file/s
---
# Startup
Example using the Hyprland Lua startup system:
```lua
hl.on("hyprland.start", function()
hl.exec_cmd("pgrep -f gzml-visual-tools >/dev/null || gzml-visual-tools")
or
hl.exec_cmd("gzml-visual-tools")
end)GZML Visual Tools is intentionally simple.
Rather than requiring large desktop frameworks or complicated configuration systems, most functionality is exposed through small standalone scripts that can be modified and extended by the user.
The goal is:
- Flexibility
- Readability
- Simplicity
- Ease of customization
My name is J (zer0-j89).
I am primarily a mycologist and technology enthusiast who began my Linux journey Arch Linux right out the gate snd fell in love ever since.
GZML Visual Tools started as a personal learning project to explore:
- Python
- GTK
- .Lua
- Linux desktop customization
while creating something useful for both myself and the wider Hyprland community. This project remains a work in progress and will continue evolving as I learn.
GZML Visual Tools
Version: 0.35
Author: zer0-j89
Status: Work In Progress
- Automatic dependency detection
- Theme management
- Additional wallpaper effects
- Additional visual controls
- Improved tray interactions
- Better support for non-Noctalia environments
git clone https://github.com/zero-j89/Hyprland-Visual-Gzml.git
cd Hyprland-Visual-Gzml
chmod +x installer/install.sh
./installer/install.shTo update type:
gzml-visual-tools-update
Directly in your terminal if your version doesn't match the repo header version.
***Note if installed prior to beta v0.5.5 you will need to run the original repo clone line above before the updater will work.
License selection is still pending.
Until an official license is chosen, please provide credit to the original project and contributors when redistributing or modifying substantial portions of the code.
⚠️ Early Release NoticeGZML Visual Tools is currently in active development. Expect bugs, rough edges, and occasional breaking changes between versions.
5/26/26 - Fixed animations path in gzml-tray.py had accidently left testing logic to my personal system.
5/29/26 - v0.35 now live! fixed a bunch of logic + added notifications to the users terminal as checks. - Added several new animations including QuantumDrift and PopSlideNstall
6/3/26 - Beta is now live!! New features and logic changes + more animations!