agentleFS
heytcassheytcass/claudeos/.claude/skills/qml-dial-in/SKILL.md

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.

The file

Files
SKILL.md

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/active in the /tmp/qs-preview copy.
  • 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, raise promoteAfter in the /tmp/qs-preview/Sessions.qml copy and relaunch qs -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 .qml blanks the entire bar — always check the reload log.
  • Stylix base16 only; never hardcode hex.
  • Theme.qml/cava.conf are 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-preview handles 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, check pgrep -x hyprlock and hyprctl monitors -j | jq '.[0].dpmsStatus' before debugging QML.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.