path: root/AGENTS.md

# 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
    window-switcher/  open windows as live previews in a grid, on ALT+TAB

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.
- **A managed save makes `virsh start` a restore, and nothing in `domstats`
  says so.** A shut-off VM carrying a saved memory image fails to start with
  `unable to execute QEMU command 'migrate-incoming'` every time, and the
  state reads a plain `shut off`. The shut-off *reason* is no help either: it
  reads `failed`, from the failed start, not from the save. `virsh list
  --all --managed-save` prints `saved` in the state column but not with
  `--name`, which is the form the panel lists with, so detection is `virsh
  dominfo <vm>` grepped for `Managed save: yes`, polled per VM the way the
  agent rows are. It measured 6ms.
- **Hyprland 0.56.2 evaluates dispatch arguments as Lua.** `dispatch
  focuswindow address:0x...` is a syntax error rather than a command, and it
  fails silently unless stderr is read. The working form is `dispatch
  hl.dsp.focus({ window = "address:0x..." })`. This is why
  `~/bin/hypr-windows.sh` is written the way it is, and its syntax was misread
  as legacy oddity worth modernising.
- **A focus dispatched while an overlay holds the keyboard is accepted and then
  ignored.** A layer surface with `keyboardFocus: Exclusive` grabs the
  keyboard, and the compositor will not move window focus out from under that
  grab. The dispatch reports `ok`, nothing moves, and no log line says
  otherwise. Closing in the same turn does not help either, because a `close()`
  that clears a property leaves the surface alive until the frame after. Focus
  after the overlay is really gone, which `window-switcher` does with a 60ms
  timer.
- **`HyprlandToplevel` has no `focusHistoryID` property.** It reads
  `undefined`, so a sort on it compares `NaN` and silently does nothing,
  leaving a plausible looking list in arbitrary order. The value is on
  `lastIpcObject`.
- **`HyprlandToplevel.address` omits the `0x`** that `hyprctl clients` prints
  and that every dispatch requires.
- **`Hyprland.toplevels` reads 0 until `refreshToplevels()` is called.**
- **An uncaptured `ScreencopyView` reports `sourceSize` of `QSize(-1, -1)`**,
  not `(0, 0)`. An aspect ratio guard has to test for a positive height: the
  obvious rewrites, `!== 0` or a truthiness check, all pass on `-1` and produce
  a negative ratio.

## 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 five. 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 four use
`ExclusionMode.Ignore` and cover the whole screen.

`window-switcher` is the fifth, with namespace `quickshell-window-switcher` and
a `blur-window-switcher` rule of its own.

## 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.