qml-dial-in
Skill1 starsChanged 18 days agoMITView on GitHub
Iterate on the bespoke Quickshell/Hyprland bar visually — animations, spacing, colours, layout. Runs the edit → fast-reload → screenshot → review loop without a full NixOS rebuild. Use when tweaking anything under home/quickshell/*.qml.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-moduleSkill
- brand-guidelinesSkill
- deploySkill
The file
Files
Quickshell bar visual dial-in
Tight visual iteration on the bar in home/quickshell/*.qml without a
rebuild per change. You must be running inside the Hyprland session (grim
needs a live compositor — verify with pgrep -x Hyprland or that
hyprctl responds). Read .claude/rules/quickshell-qml.md and the API gotchas
in docs/plans/2026-07-10-hyprland-handoff.md first.
The loop
1. Edit the source
Edit the .qml files in home/quickshell/ (the real source — the preview reads
from here, so there's no separate "port back" step).
2. Fast-reload + screenshot
qml-preview # copies deployed config + overlays repo QML, relaunches, screenshots
qml-preview --build # same, but from THIS checkout's generated config dir (needed when
# Keybinds.qml/Theme.qml/... change — the deployed copy predates you)It writes the shot to /tmp/qs-preview.png and exits non-zero on a QML load
error (printing the offending file:line). If qml-preview isn't on PATH yet
(needs one rebuild to install), run the script directly:
"$(git rev-parse --show-toplevel)"/home/qml-preview.sh. It overlays the QML of the
checkout you run it from (your worktree); CLAUDEOS_DIR overrides.
Under the hood it: copies the deployed ~/.config/quickshell (for the
generated Theme.qml + cava.conf), overlays the repo's home/quickshell/*.qml
into /tmp/qs-preview, stops the running bar, launches qs -p, and grabs a
screenshot. The next rebuild restores the real bar.
3. Review
Read /tmp/qs-preview.png. To inspect one region (e.g. just the island),
re-grab it: grim -g "400,0 480x40" /tmp/qs-region.png (coords are logical px;
the bar is Theme.barHeight tall at the top). For animations, grab 2–3 frames a
beat apart to confirm motion.
To exercise a state that isn't currently true, drive it directly rather than faking it in the QML:
- media/spectrum: play audio (any MPRIS source); or briefly force the island
state/activein the/tmp/qs-previewcopy. - notification peek / toast:
gdbus call --session --dest org.freedesktop.Notifications --object-path /org/freedesktop/Notifications --method org.freedesktop.Notifications.Notify "App" 0 "" "Summary" "Body" "[]" "{}" 5000 - agent pulse:
echo "any phrase" > "$XDG_RUNTIME_DIR/claudeos-agent.d/manual"(remove to clear; the island shows the file's first line). - session count / promoted face: driven by
~/.claude/sessions/*.json(Sessions.qml). Your own session is always busy while you work, so the clock face shows at least "✳ 1" and, after 90 s, promotes your session's title to the face. To see the plain clock face, raisepromoteAfterin the/tmp/qs-preview/Sessions.qmlcopy and relaunchqs -p.
4. Iterate
Tweak, re-run qml-preview, re-review. Keep the loop tight — seconds, not a
rebuild.
5. Bake it in
When happy: nix build .#nixosConfigurations.transporter.config.system.build.toplevel
(+ nix fmt), commit, then rebuild → reboot to restore the real bar
(Hyprland is the default generation — no specialisation, no (hyprland) boot
entry). After a plain switch, relaunching qs also picks up the new config.
Gotchas (see the rule file for the full set)
- One broken
.qmlblanks the entire bar — always check the reload log. - Stylix base16 only; never hardcode hex.
Theme.qml/cava.confare generated — that's why the preview copies the deployed dir rather than running the repo dir directly.- hyprlock/hypridle: the 5-min idle lock would interrupt long dial-in
stretches, and grim on a locked screen silently captures the lock screen /
wallpaper instead of the bar.
qml-previewhandles both: it refuses to run while hyprlock is up, and every run refreshes an agent marker (claudeos-agent.d/qml-dial-in) that holds Caffeine's idle-inhibit through the bar — the marker ages out 60 min after the last run. If a screenshot unexpectedly shows only wallpaper, checkpgrep -x hyprlockandhyprctl monitors -j | jq '.[0].dpmsStatus'before debugging QML.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

