homelab/dotfiles/quickshell/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Quickshell configuration — a QML-based Wayland desktop shell (bar, launcher, tray, decorations) for a Hyprland/wlroots setup. ~/.config/quickshell is a symlink to this repo, so Quickshell loads shell.qml here as the "default" config.

Running / testing changes

qs                 # runs ~/.config/quickshell/shell.qml (this repo, since it's the symlinked default config)
qs -p .            # run this directory explicitly regardless of symlink
qs -n              # exit immediately if another instance is already running (use to avoid duplicate shells while iterating)

Quickshell hot-reloads QML on file save when already running, so for most edits just save and check the running instance rather than restarting qs. There is no separate build/lint/test tooling in this repo — verification is visual/behavioral via the running shell. qmlls (QML language server) is configured via .qmlls.ini for editor diagnostics.

Architecture

shell.qml is the entry point: a Scope that instantiates the top-level pieces — Bar, BarBottom, BarTop, and a hidden Launcher — as siblings. Each top-level widget manages its own PanelWindow(s); there's no central layout manager.

Import convention: QML modules are imported by their path under the repo root using the qs. namespace, e.g. import qs.widgets.launcher, import qs.widgets.decoration. Sibling files in the same directory are imported with a relative string import instead (e.g. Bar.qml does import "modules").

Multi-monitor: Bar/BarTop/BarBottom each wrap their PanelWindow in Variants { model: Quickshell.screens }, so one window instance is created per connected screen. pragma ComponentBehavior: Bound + required property var modelData is the standard pattern for these per-screen delegates.

Directory layout:

• widgets/bar/ — Bar.qml is the main sidebar (right-anchored, full height) hosting the module stack (date, clock, tray, decorative dividers); BarTop.qml/BarBottom.qml are thin accent-colored strips anchored to the top/bottom edges.
• widgets/bar/modules/ — individual bar widgets (Clock, Date, Tray/TrayItem, Volume) built on the shared BarWidget base component.
• widgets/launcher/ — shared AppModel search/execution plus eight launcher variants. ApplicationLauncher (variant 8 and the primary SUPER launcher) keeps its visual core in the headlessly renderable ApplicationLauncherContent; variants 1–7 remain available on SUPER CTRL 1–7 for comparison.
• widgets/decoration/ — reusable QtQuick Shape-based visual accents (angled panel edges, slashes) used to give bar panels their non-rectangular look. Dummy.qml is a placeholder/test rectangle.
• widgets/input/ — thin wrappers around QtQuick.Controls inputs (currently just TextField).
• widgets/layout/ — HorizontalStack/VerticalStack: RowLayout/ColumnLayout wrappers that expose default property alias content for terser call sites, with a trailing filler Item that soaks up remaining space.
• assets/ — SVG icons referenced via file://${Quickshell.shellDir}/assets/....

Styling: All colors and font families come from the Theme singleton (widgets/theme/Theme.qml, import qs.widgets.theme) — there are no color or font literals left anywhere under widgets/. Add a token there rather than hardcoding a value; alpha variants of the two main colors go through Theme.textAlpha(a) / Theme.accentAlpha(a) instead of a hand-written Qt.rgba(...). Metrics (sizes, spacing) are still per-component.

Component base pattern: BarWidget.qml (widgets/bar/modules/BarWidget.qml) is a WrapperMouseArea + WrapperRectangle combo providing hover-triggered border highlight (Behavior on border.color animation) and Layout.fillWidth. Bar modules extend it via default property alias content rather than duplicating the hover/border chrome.

Fonts: Two families, both via Theme. Theme.displayFont / Theme.readoutFont (an alias of it) are DepartureMono Nerd Font, installed by services/desktop/desktop-apps.nix; Theme.microFont is DejaVu Sans Mono. The shell no longer uses Digital-7 Mono, which was never packaged and depended on a manual ~/.dots/fonts/digital_7 install.