repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(hypr): update ecosystem tool guidance

ba0a91e36c19b21d7f96d91b5890968c293f81e0

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

skills/hypr/SKILL.md

Modified
82 82 Lua config stays Lua; legacy hyprlang stays legacy.
83 83 - Prefer small config modules and comments over monolith edits.
84 84 - Never install/start competing daemons without saying what it replaces.
85 +- Keep skill/reference updates general-purpose; never bake one user's monitor
86 + names, paths, theme, services, or rice decisions into the skill.
85 87 - For config copied from GitHub, treat as inspiration, not authoritative.

skills/hypr/references/ecosystem-taxonomy.md

Modified
34 34 | Blue-light/gamma | hyprsunset | wlsunset, gammastep where Wayland works | avoid simultaneous gamma filters |
35 35 | App launcher | hyprlauncher | fuzzel, walker, rofi-wayland, wofi, tofi, bemenu, anyrun, vicinae | many can coexist; choose one primary bind |
36 36 | System info | hyprsysteminfo | inxi, fastfetch | diagnostic frontend |
37 -| Password UI | hyprpwcenter | pass/secret-service frontends | optional |
37 +| PipeWire control GUI | hyprpwcenter | pavucontrol, pwvucontrol | optional audio/graph frontend |
38 38 | Qt integration/theme | hyprland-qt-support, hyprqt6engine | qt5ct/qt6ct, Kvantum | toolkit theming overlap |
40 40 ## Bars, panels, shells

skills/hypr/references/hypr-tools.md

Modified
1 -# Hypr tools
1 +# Hypr ecosystem tools
3 -First-party Hypr apps are version-sensitive.
4 -Check installed tool help and current Hypr wiki before copying config.
3 +Official Hypr ecosystem docs target latest `-git`.
4 +Installed distro packages may lag.
5 +For exact local behavior, check installed binaries, packaged unit files, and
6 +current wiki source before editing.
8 +Keep this guidance general-purpose.
9 +Do not encode one user's rice, monitor names, wallpaper paths, services, or
10 +theme choices in this skill.
6 12 ## User apps/utilities
8 -| Tool | Role | Overlaps |
9 -| ----------------------------- | ----------------------- | --------------------------------------------------------- |
10 -| `hyprpaper` | wallpaper daemon | swaybg, wpaperd, swww/awww, mpvpaper |
11 -| `hyprpicker` | screen color picker | wl-color-picker, grim/slurp picker scripts |
12 -| `hyprlauncher` | launcher/picker | fuzzel, walker, rofi-wayland, wofi, tofi, anyrun |
13 -| `hypridle` | idle daemon | swayidle |
14 -| `hyprlock` | lock screen | swaylock, gtklock |
15 -| `xdg-desktop-portal-hyprland` | portal backend | required for Hyprland screencast/global-shortcut features |
16 -| `hyprsysteminfo` | system info GUI | fastfetch, inxi frontends |
17 -| `hyprsunset` | blue-light/gamma | wlsunset, gammastep, compositor shaders |
18 -| `hyprpolkitagent` | polkit auth agent | polkit-kde-agent, GNOME polkit agent |
19 -| `hyprpwcenter` | PipeWire control center | pavucontrol, pwvucontrol, other audio GUIs |
20 -| `hyprshutdown` | graceful shutdown UI | wlogout, rofi/quickshell power menus |
21 -| `hyprland-qt-support` | Qt/Hypr integration | qt platform/theme glue |
22 -| `hyprqt6engine` | Qt6 theme engine | qt6ct, Kvantum, KDE color scheme tooling |
14 +| Tool | Role | Config path | Runtime/startup |
15 +| ----------------------------- | ----------------------- | ------------------------------------------------ | --------------------------------------------------- |
16 +| `hyprpaper` | wallpaper daemon | `~/.config/hypr/hyprpaper.conf` optional | `hyprpaper` or packaged `hyprpaper.service` |
17 +| `hyprpicker` | color picker | none | one-shot CLI flags |
18 +| `hyprlauncher` | launcher/picker | `~/.config/hypr/hyprlauncher.conf` optional | bind `hyprlauncher`; it manages its own daemon |
19 +| `hypridle` | idle daemon | `~/.config/hypr/hypridle.conf` required | `hypridle` or packaged `hypridle.service` |
20 +| `hyprlock` | lock screen | `~/.config/hypr/hyprlock.conf` required | one-shot `hyprlock`; often called by hypridle |
21 +| `xdg-desktop-portal-hyprland` | portal backend | `~/.config/hypr/xdph.conf` optional | D-Bus autostart; do not normally autostart manually |
22 +| `hyprsysteminfo` | system info GUI | none | one-shot GUI |
23 +| `hyprsunset` | blue-light/gamma daemon | `~/.config/hypr/hyprsunset.conf` optional | `hyprsunset` or packaged `hyprsunset.service` |
24 +| `hyprpolkitagent` | polkit auth agent | none | packaged service or session autostart |
25 +| `hyprland-qt-support` | QML style for hypr apps | `~/.config/hypr/application-style.conf` optional | loaded by supported Qt/QML Hypr apps |
26 +| `hyprqt6engine` | Qt6 platform theme | `~/.config/hypr/hyprqt6engine.conf` optional | set `QT_QPA_PLATFORMTHEME=hyprqt6engine` |
27 +| `hyprpwcenter` | PipeWire GUI | none documented | one-shot GUI |
28 +| `hyprshutdown` | graceful Hyprland exit | none documented | bind `hyprshutdown` |
24 -## Dev libs/tooling
30 +## Startup rules
26 -| Tool | Role |
27 -| --------------------- | -------------------------------------------------- |
28 -| `hyprtoolkit` | C++ GUI toolkit for native Wayland apps |
29 -| `hyprcursor` | Hypr cursor theme format/support |
30 -| `hyprutils` | shared utility library |
31 -| `hyprlang` | legacy Hypr config language/parser library |
32 -| `hyprwayland-scanner` | Wayland protocol source/header generator |
33 -| `aquamarine` | rendering/backend library |
34 -| `hyprgraphics` | graphics utility library |
35 -| `hyprland-guiutils` | GUI utility helpers/successor area for old qtutils |
32 +- If docs/package ships a user unit, prefer that unit over custom copies:
33 + `systemctl --user cat hyprpaper.service` etc.
34 +- Packaged user units commonly exist for `hyprpaper`, `hypridle`, `hyprsunset`,
35 + `hyprpolkitagent`.
36 + Verify before assuming.
37 +- Under UWSM/user-service setups, use `systemctl --user enable --now
38 + <unit>.service`.
39 +- Otherwise preserve compositor autostart style, e.g. `hl.exec_cmd("hypridle")`.
40 +- Do not create custom `ExecStartPost` wallpaper/theme hacks unless explicitly
41 + requested.
42 +- Do not start competing daemons silently.
43 + State replacements first.
44 +- Do not manually autostart XDPH in normal setups; D-Bus starts it.
37 -Dev libs matter for packaging/plugins/build errors, not normal desktop config.
46 +## `hyprlauncher`
39 -## No first-party Hypr tool exists
48 +Docs state hyprlauncher is always a daemon internally.
49 +Simplest correct setup:
41 -| Role | Default primitive | Higher-level choices |
42 -| ----------------- | ------------------------------- | ------------------------------------------------------ |
43 -| notifications | FreeDesktop notification daemon | mako=minimal, swaync=center, dunst/fnott |
44 -| screenshots | grim + slurp + wl-clipboard | hyprshot/HyprCapture wrappers, satty/swappy annotation |
45 -| screen recording | PipeWire/portal or wf-recorder | OBS, wl-screenrec |
46 -| clipboard history | wl-clipboard primitive | cliphist, CopyQ Wayland mode |
47 -| status bar/shell | layer-shell client | Waybar, ashell, Quickshell, AGS/Astal, Eww |
51 +```lua
52 +hl.bind("SUPER + Space", hl.dsp.exec_cmd("hyprlauncher"), { description = "launcher" })
53 +```
49 -Prefer first-party only where it exists and fits.
50 -Do not invent Hypr-native ownership for generic Wayland roles.
55 +Rules:
57 +- No wrapper needed for normal use.
58 +- No autostart needed for normal use.
59 +- `hyprlauncher -d` starts daemon without opening; only use for intentional warm
60 + start/perf tuning.
61 +- Dmenu mode:
62 + feed stdin to `hyprlauncher --dmenu`.
63 +- Optional config:
64 + `~/.config/hypr/hyprlauncher.conf`.
65 +- Theme comes from `hyprtoolkit`.
67 +Key config categories/options:
69 +```ini
70 +general:grab_focus = true
71 +cache:enabled = true
72 +finders:default_finder = desktop
73 +finders:desktop_launch_prefix =
74 +finders:desktop_icons = true
75 +ui:window_size = 400 260
76 +```
78 +## `hyprpaper`
80 +Current wiki syntax uses anonymous `wallpaper { ...
81 +}` blocks, not old `preload = ...` + `wallpaper = MON,PATH` lines.
83 +```ini
84 +wallpaper {
85 + monitor =
86 + path = ~/wallpapers/fallback.png
87 + fit_mode = cover
90 +splash = false
91 +ipc = true
92 +```
94 +Rules:
96 +- Config path:
97 + `~/.config/hypr/hyprpaper.conf`; optional.
98 +- `monitor =` may be empty → fallback wallpaper.
99 +- `path = ~/...` is valid; do not expand to `/home/...` just to appease parser.
100 +- `fit_mode`:
101 + `contain` | `cover` | `tile` | `fill`; default `cover`.
102 +- Directory `path` may use `timeout`, `order = random`, `recursive`.
103 +- `source = ~/.config/hypr/hyprpaper.d/*.conf` supports globbing, tilde
104 + expansion, relative paths; parse order is linear.
105 +- IPC:
106 + `hyprctl hyprpaper wallpaper '[mon], [path], [fit_mode]'`; `mon` may be empty
107 + for fallback, fit mode optional.
109 +## `hypridle`
111 +Config is required; daemon exits without one.
113 +```ini
114 +general {
115 + lock_cmd = pidof hyprlock || hyprlock
116 + before_sleep_cmd = loginctl lock-session
117 + after_sleep_cmd = hyprctl dispatch dpms on
120 +listener {
121 + timeout = 300
122 + on-timeout = loginctl lock-session
124 +```
126 +Rules:
128 +- Config path:
129 + `~/.config/hypr/hypridle.conf`.
130 +- `general` covers D-Bus lock/unlock, sleep hooks, inhibitor behavior.
131 +- `listener` blocks define `timeout`, `on-timeout`, `on-resume`,
132 + `ignore_inhibit`.
133 +- Common safe pattern:
134 + `lock_cmd = pidof hyprlock || hyprlock`.
135 +- For suspend:
136 + prefer `before_sleep_cmd = loginctl lock-session`.
137 +- `inhibit_sleep` default is auto; do not override without reason.
139 +## `hyprlock`
141 +Config is required.
142 +If no config is found, hyprlock exits and the session is not locked.
144 +Search order:
146 +1. `$XDG_CONFIG_HOME/hypr/hyprlock.conf`
147 +2. `$HOME/.config/hypr/hyprlock.conf`
148 +3. `$XDG_CONFIG_DIRS/*/hypr/hyprlock.conf`
149 +4. `/etc/xdg/hypr/hyprlock.conf`
151 +Minimal shape:
153 +```ini
154 +general {
155 + hide_cursor = true
158 +background {
159 + monitor =
160 + path = screenshot
161 + blur_passes = 2
164 +input-field {
165 + monitor =
166 + size = 400, 90
167 + position = 0, 0
168 + halign = center
169 + valign = center
171 +```
173 +Rules:
175 +- `monitor =` empty means all monitors for widgets.
176 +- Widget positioning uses `halign`, `valign`, `position`, `zindex`.
177 +- `background:path = screenshot` is supported.
178 +- Labels/images can run commands; never use non-exiting commands.
179 +- Recovery:
180 + `pkill -USR1 hyprlock` unlocks; mention before risky lock edits.
181 +- Locked Hyprland binds need lock flag (`l`) to work while locked.
183 +## `hyprsunset`
185 +Config optional but recommended for scheduled profiles.
187 +```ini
188 +max-gamma = 150
190 +profile {
191 + time = 7:30
192 + identity = true
195 +profile {
196 + time = 21:00
197 + temperature = 5500
198 + gamma = 0.8
200 +```
202 +Rules:
204 +- Config path:
205 + `~/.config/hypr/hyprsunset.conf`.
206 +- Supported since Hyprland 0.45.0.
207 +- Profiles activate by clock time; startup applies current profile.
208 +- `identity = true` disables color-temperature shift while allowing gamma.
209 +- IPC:
210 + - `hyprctl hyprsunset temperature 2500`
211 + - `hyprctl hyprsunset identity`
212 + - `hyprctl hyprsunset gamma 50` or `+10`/`-10`
213 + - `hyprctl hyprsunset reset [temperature|gamma|identity]`
214 +- Gamma degrades color accuracy; prefer real brightness controls if available.
216 +## `hyprpolkitagent`
218 +Polkit auth agent; required for GUI elevation prompts.
219 +No config documented.
221 +Rules:
223 +- Prefer packaged `hyprpolkitagent.service` under UWSM/user services.
224 +- Otherwise autostart `systemctl --user start hyprpolkitagent` or the binary.
225 +- Binary path varies by distro:
226 + `/usr/lib/hyprpolkitagent/hyprpolkitagent`, `/usr/libexec/hyprpolkitagent`,
227 + `/usr/lib64/libexec/hyprpolkitagent`.
228 +- Only one polkit agent should run.
230 +## `hyprpicker`
232 +No config; launch with flags.
234 +Common flags:
236 +```bash
237 +hyprpicker --autocopy
238 +hyprpicker --autocopy --format rgb
239 +hyprpicker --notify --lowercase-hex
240 +```
242 +Useful options:
243 +`--format cmyk|hex|rgb|hsl|hsv`, `--output-format`, `--no-zoom`,
244 +`--render-inactive`, `--scale`, `--radius`, `--quiet`.
246 +## `hyprshutdown`
248 +Graceful Hyprland exit UI.
249 +Recommended over raw compositor exit when apps should close cleanly.
251 +```lua
252 +hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("hyprshutdown"), { description = "power" })
253 +```
255 +Useful flags:
257 +- `--dry-run`
258 +- `--no-exit`
259 +- `--top-label` / `-t`
260 +- `--post-cmd` / `-p` for shutdown/reboot after Hyprland exits
261 +- `--vt N` for NVIDIA+SDDM VT handoff issues
262 +- `--no-fork`, `--verbose`
264 +Do not add passwordless `chvt` sudo rules without explicit user approval.
266 +## XDPH (`xdg-desktop-portal-hyprland`)
268 +Provides screenshare/global-shortcut portals.
269 +Does not implement file picker; install GTK/KDE portal as fallback.
271 +Rules:
273 +- D-Bus starts XDPH when needed; do not normally autostart/kill-loop it.
274 +- Config path:
275 + `~/.config/hypr/xdph.conf`.
276 +- Useful config:
278 +```ini
279 +screencopy {
280 + max_fps = 60
281 + allow_token_by_default = false
282 + custom_picker_binary = hyprland-share-picker
283 + force_shm = false
285 +```
287 +- Debug with:
288 + `systemctl --user status xdg-desktop-portal-hyprland xdg-desktop-portal`.
289 +- For file picker preference, use
290 + `~/.config/xdg-desktop-portal/hyprland-portals.conf`, not `xdph.conf`.
292 +## Hypr Qt/theme tools
294 +### `hyprtoolkit`
296 +General toolkit theme config for Hypr ecosystem apps:
297 +`~/.config/hypr/hyprtoolkit.conf`.
299 +```ini
300 +background = 0xFF181818
301 +base = 0xFF202020
302 +text = 0xFFDADADA
303 +alternate_base = 0xFF272727
304 +bright_text = 0xFFFFDEDE
305 +accent = 0xFF00FFCC
306 +accent_secondary = 0xFF0099F0
307 +font_family = Sans Serif
308 +font_family_monospace = monospace
309 +rounding_large = 10
310 +rounding_small = 5
311 +```
313 +Also supports `h1_size`, `h2_size`, `h3_size`, `font_size`, `small_font_size`,
314 +`icon_theme`.
316 +### `hyprland-qt-support`
318 +QML style for hypr* Qt6 apps.
319 +Config:
320 +`~/.config/hypr/application-style.conf`.
322 +```ini
323 +roundness = 1
324 +border_width = 1
325 +reduce_motion = false
326 +```
328 +### `hyprqt6engine`
330 +Qt6 platform theme replacement for qt6ct.
331 +Use only if installed:
333 +```lua
334 +hl.env("QT_QPA_PLATFORMTHEME", "hyprqt6engine")
335 +```
337 +Config:
338 +`~/.config/hypr/hyprqt6engine.conf`.
340 +```ini
341 +theme:color_scheme =
342 +theme:icon_theme =
343 +theme:style = Fusion
344 +theme:font = Sans Serif
345 +theme:font_size = 11
346 +theme:font_fixed = monospace
347 +theme:font_fixed_size = 11
348 +misc:single_click_activate = true
349 +misc:menus_have_icons = true
350 +misc:shortcuts_for_context_menus = true
351 +```
353 +## Other user utilities
355 +- `hyprsysteminfo`:
356 + GUI to display/copy Hyprland/system info.
357 + No config.
358 +- `hyprpwcenter`:
359 + PipeWire graph/control GUI.
360 + No config documented.
362 +## Cursor/support/dev tools
364 +- `hyprcursor`:
365 + cursor theme format.
366 + Set `HYPRCURSOR_THEME` and `HYPRCURSOR_SIZE`; also set
367 + `XCURSOR_THEME`/`XCURSOR_SIZE` for apps that fall back to XCursor.
368 + Themes should live in `~/.local/share/icons` or `~/.icons`.
369 +- `hyprlang`:
370 + config language/parser for hypr* apps.
371 + Supports categories, variables, comments with `#`, inline `category:option`,
372 + arithmetic `{{A + B}}`, and conditionals.
373 + App-specific keywords such as `source` vary by tool.
374 + Preserve syntax family.
375 +- `hyprutils`, `hyprgraphics`:
376 + shared libraries; no normal desktop config.
377 +- `hyprwayland-scanner`:
378 + C++ Wayland protocol code generator; dev only.
379 +- `aquamarine`:
380 + rendering backend library; configured by env vars like `AQ_DRM_DEVICES`,
381 + `AQ_NO_MODIFIERS`, `AQ_NO_ATOMIC`.
382 + Use only for backend/GPU troubleshooting.
383 +- `hyprland-guiutils`:
384 + GUI utility helpers/successor area for old qtutils.
52 386 ## Inspection
54 388 ```bash
55 389 hyprpaper --help
56 -hyprlock --help
57 -hypridle --help
58 -hyprsunset --help
59 -hyprshutdown --help
60 390 hyprpicker --help
61 391 hyprlauncher --help
62 -systemctl --user status hyprpaper hypridle hyprsunset hyprpolkitagent
392 +hypridle --help
393 +hyprlock --help
394 +hyprsunset --help
395 +hyprshutdown --help
396 +systemctl --user cat hyprpaper hypridle hyprsunset hyprpolkitagent
397 +systemctl --user status hyprpaper hypridle hyprsunset hyprpolkitagent xdg-desktop-portal-hyprland xdg-desktop-portal
63 398 journalctl --user -b | grep -Ei 'hyprpaper|hyprlock|hypridle|hyprsunset|polkit|xdg-desktop-portal'
66 401 ## Editing rules
68 -- Preserve the user's config format and module layout.
69 -- Do not start competing daemons silently.
70 -- State what each daemon replaces before enabling it.
71 -- Prefer `systemctl --user` units when the user's setup already uses user
72 - services; otherwise preserve compositor autostart style.
403 +- Preserve user's config format and module layout.
404 +- Remove wrappers/custom units when upstream docs/package provide a simple path.
405 +- Avoid configs for tools with no documented config.
406 +- Avoid absolute paths if docs support `~` or relative paths.
407 +- Never install/start competing daemons without saying what it replaces.
73 408 - For lock/idle changes, describe emergency unlock/recovery path first.