1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
# AGENTS.md
Guidance for agents working in this repository.
## What this is
Quickshell components for a Hyprland desktop, one per directory, each a
complete shell in its own right. They are not modules of a single bar: any of
them runs alone, and running one does not require the others.
volume-osd/ volume for output and input, plus what is playing
vm-manager/ libvirt drawer: state, live stats, snapshots
appearance/ wallpaper picker and colour scheme switcher
mail-overview/ notmuch unread counts per account, waybar icon and drawer
They are started from `~/.config/hypr/sections/autostart.lua` and keep running
for the whole session.
## The rule that bites first
**A quickshell config with no visible window exits.** These components are
hidden most of the time, so each holds itself open with a 1x1 transparent
`PanelWindow` with `mask: Region {}`, which is click-through and draws nothing.
Without it the shell loads, logs `Configuration Loaded`, reports no error, and
quits. The symptom is never an error message: it is a keybind that appears to
do nothing, or a panel that never paints. This was removed once during
development because a process check was measuring the wrong thing, and two
components broke in exactly that way. Any new component needs the same window.
## Verifying, and how not to
Two traps cost real time in this repo, both about measurement rather than code.
**A detached `qs` does not survive an agent's tool call.** Starting one with
`&`, `nohup` or `setsid -f` and then checking `pgrep` in a later call reports
`DEAD` regardless of whether the config is sound. That reads exactly like the
no-visible-window exit above and sent a debugging session in the wrong
direction for a dozen calls. Start it so the harness owns the process, and
confirm with the log rather than a later `pgrep`.
**The process is called `qs`, not `quickshell`.** Both binaries ship, but `qs`
is what runs, so `pkill -x quickshell` and `pgrep -x quickshell` match nothing
and silently succeed. During development this meant every "stopped" was a lie
and every restart stacked another instance: 47 accumulated before the user
noticed. It also produced "0 processes" readings that were mistaken twice for
the shell exiting, and sent a debugging session after a bug that was not
there. Use `pkill -x qs` and `pgrep -cx qs`, and check the count after.
**`pkill -f` matches the agent's own shell.** The working directory is in the
command line, so `pkill -f qs` or `pkill -f "foo.qml"` kills the caller and
returns 144. Always `-x`, never `-f`.
For anything visual, ask. Screenshots of a transient OSD are a race, and the
user has the screen.
## Per-component notes
Each directory's README carries its own, and they are worth reading before
changing that component. The ones that generalise:
- **PipeWire nodes report their initial volume before `ready` goes true.** The
`ready` check alone suppresses the startup values. An extra guard on top of
it ate the user's first keypress instead.
- **`PwObjectTracker` is not optional.** Node properties only stay current
while something binds the node; without it the volume reads once and goes
stale.
- **playerctld publishes a duplicate of every MPRIS player** under its own bus
name. Filter by `dbusName`, not by identity.
- **Key events reach a focused item, not a window.** Setting
`WlrLayershell.keyboardFocus` is necessary but not sufficient:
`Keys.onEscapePressed` on a `PanelWindow` never fires.
- **A `Row` sizes to its children, not its parent.** Fixed child widths inside
one overflowed the panel and pushed a button past its edge.
- **QML's JS engine has no `String.matchAll`.** It throws, and inside a `try`
that looks like a parser quietly returning nothing. Use an `exec` loop.
- **Assigning `running = true` to a `Process` that is already running does
nothing.** Reusing one `Process` for a sequence of commands needs
`running = false` immediately before each start.
- **`notmuch` fails two different ways and only one is detectable.** A
rejected query prints nothing and exits 1; a query Xapian merely misparses
returns a plausible wrong number and exits 0 (`tag:unread and ((` gave 41).
Validate the output as an integer, which catches the first, where empty
output would otherwise render as an empty inbox. Nothing catches the second,
so keep such queries as fixed strings.
- **notmuch deduplicates by message id, so one message can have several
paths.** A message that arrived at two configured addresses is counted by
both accounts under a `path:` glob, and per-account counts then sum above the
total. The `account-*` tag is a property of the message, so it is singular.
- **Xapian replaces files on commit.** A watch held on a filename inside the
database directory dies with the file; watch the directory for
`close_write,moved_to` instead, and debounce, because one commit touches
several files.
- **An INI section body is not "everything up to the next `[`".** Values can
themselves contain brackets: `qtmaildir.conf` has folders named
`[Gmail]/Bozze`, which ended a section before its `label` and made three of
five accounts silently display their raw key. Walk lines instead. A first fix
using a lazy quantifier and a lookahead dropped every label, which is the
argument for the boring version.
- **libvirt's own memory and disk figures are not what they look like.**
`balloon.current` is memory allocated to the VM and reads full forever;
`block.allocation` is qcow2 growth on the host, not usage inside the guest.
The real numbers come from qemu-guest-agent, and the panel shows a dash
rather than substituting the host-side ones.
## Theme
No component defines a palette. `udt-accent`, in the
`unified-desktop-theme` repo alongside this one, writes
`~/.cache/wal/udt-palette.qml` from its `palette.rasi`, carrying the whole
Catppuccin Macchiato palette plus the accent snapped from the current
wallpaper. `Theme.qml` parses and watches that file, so a palette edit
recolours a running shell with no restart.
What is left in `Theme.qml` is a fallback for before the file is read, and for
a machine without unified-desktop-theme. Do not grow it into a second palette:
that duplication is what generating the file removed.
The file is parsed rather than imported because a generated QML singleton
cannot be imported without a `qmldir` beside it, and the wal cache has no
reason to carry one.
There is one `Theme.qml`, in `shared/`, and each component holds a symlink to
it. It was four copies that had already drifted: `vm-manager` was missing
`surfaceAlt` and `volume-osd` was missing `green`, `yellow` and `surfaceAlt`,
so the shared file is the superset and the two thin ones gained properties
they never had. A symlink rather than a shared import path because a singleton
outside the config directory needs a `qmldir`, which is the same friction that
keeps the palette parsed rather than imported; quickshell follows the link and
resolves the singleton with no qmldir and no consumer change. Editing any
component's `Theme.qml` edits all four. Do not replace a link with a copy.
## Blur
Translucency is set in QML; the frosting is the compositor's. Hyprland blurs a
layer surface only when a rule names it, matched on the namespace the window
sets, in `~/.config/hypr/sections/decorations.lua`. A new component that wants
frosting needs its own `hl.layer_rule` and a distinct
`WlrLayershell.namespace`. Without the rule it still works, rendering flat
translucent.
A panel that should sit below waybar rather than over it wants
`exclusionMode: ExclusionMode.Normal` on its window, which respects waybar's
exclusive zone without the component knowing the bar's height. Measured with
`hyprctl layers`: waybar at `y=-540 h=42`, a `Normal` overlay on the same
screen at `y=-498 h=1038`, starting exactly where the bar ends, so the
backdrop never dims it. `mail-overview` does this; the other three use
`ExclusionMode.Ignore` and cover the whole screen.
## Reloading
| | How |
| --- | --- |
| a component's QML | quickshell hot-reloads on save; no restart |
| palette | regenerate with `udt-accent <wallpaper>`; watched, no restart |
| Hyprland binds, layer rules, autostart | `hyprctl reload` |
Hot reload covers adding and removing windows too: the keepalive window above
was added to a running shell and took effect on save.
`qs -p <dir>` runs one directly. `qs -p <dir> ipc call <target> <fn>` reaches a
running one, which is how `SUPER+v` opens the VM drawer.
## Conventions
- GPLv2 only, with the header notice in every source file.
- Commits carry the reasoning, not just the change: several of the notes above
exist because a commit message explained why something was the way it was.
- No home paths in committed files. A gitleaks hook blocks them and has been
right every time; `~` in documentation, absolute paths only in the live
Hyprland config, which is not in this repo.
|
