s0wlz (Matthias Puchstein)
c5f7162ebb
- Vertical bar on DP-2 with rounded-square pills throughout - Per-monitor workspace groups sorted by screen x position, with Nerd Font icons for named workspaces and apex-neon red active indicator - Bar layout: datetime+weather top, workspaces centered, gamemode+media+notif+system bottom - Popouts anchor to triggering icon (top-right for datetime/weather, bottom-right for media/notif/system) - Lock command switched from hyprlock to swaylock - Hyprland blur/ignore_alpha layerrules for quickshell namespace Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Is
|
|
|
|
A Quickshell (v0.2.x) desktop shell configuration for Hyprland on Arch Linux. It renders a vertical bar on the right edge of the screen with popout panels. Written entirely in QML using Quickshell's extended Qt Quick modules.
|
|
|
|
## Running / Reloading
|
|
|
|
```bash
|
|
quickshell # launch (reads shell.qml from ~/.config/quickshell/)
|
|
quickshell -c /path/to/dir # launch from a different config dir
|
|
```
|
|
|
|
Quickshell hot-reloads on file save — no restart needed during development. If the shell crashes or gets stuck, `killall quickshell && quickshell &` to restart.
|
|
|
|
## Architecture
|
|
|
|
### Entry Point
|
|
|
|
`shell.qml` — `ShellRoot` that instantiates three top-level components:
|
|
1. `NotificationDaemon` — D-Bus notification server
|
|
2. `Bar` — the main bar + popout overlay
|
|
3. `Osd` — volume/mic OSD overlay
|
|
|
|
### Bar (`Bar.qml`)
|
|
|
|
Uses `Variants` over `Quickshell.screens` to create per-monitor `PanelWindow` instances (filtered to `Config.monitor`). Two window layers:
|
|
- **Bar window** — fixed-width right-anchored panel with pill-shaped widgets
|
|
- **Popout window** — transparent overlay with animated `PopoutSlot` components that appear left of the bar
|
|
|
|
Bar pills (notification, workspaces, weather, datetime, system) toggle popouts via the `PopoutState` singleton.
|
|
|
|
### Shared Singletons (`shared/`)
|
|
|
|
All four are `pragma Singleton`:
|
|
- **Config** — user settings (monitor=DP-2, weatherLocation=Nospelt, power commands, disk mounts, formats); `.tmpl` file driven by chezmoi data
|
|
- **Theme** — Apex-neon/aeon colors (replaces Catppuccin), layout constants, typography (GeistMono Nerd Font), animation durations
|
|
- **PopoutState** — which popout is active (`active` string + `triggerY`), with `toggle()`/`close()`
|
|
- **Time** — `SystemClock`-backed formatted time strings
|
|
- **Weather** — fetches from `wttr.in`, parses JSON, exposes current + forecast data
|
|
|
|
### Popout Pattern
|
|
|
|
Each popout follows the same structure:
|
|
1. A `BarPill` in the bar column (toggles `PopoutState`)
|
|
2. A `PopoutSlot` in `Bar.qml` (handles animation — fade, scale, slide)
|
|
3. A popout component in `bar/popouts/` wrapped in `PopoutBackground` (rounded left, flush right)
|
|
|
|
### Data Fetching
|
|
|
|
`SystemPopout` polls system stats via `Process` + `StdioCollector`:
|
|
- CPU, memory, temperature, GPU (via `scripts/gpu.sh`), disk, network, updates
|
|
- Different refresh intervals: 5s (CPU/mem/temp/GPU), 30s (disk/net), 5min (updates)
|
|
|
|
Weather uses `curl wttr.in` with a 30-minute refresh timer.
|
|
|
|
### Quickshell-Specific Patterns
|
|
|
|
- `Variants { model: Quickshell.screens }` — per-screen window instantiation
|
|
- `PanelWindow` with `anchors`/`margins`/`exclusiveZone` — Wayland layer-shell positioning
|
|
- `Scope` — non-visual Quickshell container for grouping logic
|
|
- `Process` + `StdioCollector { onStreamFinished }` — async shell command execution
|
|
- `PwObjectTracker` — required to track PipeWire default sink/source changes
|
|
- `Quickshell.Hyprland` — workspace state and `Hyprland.dispatch()` for IPC
|
|
|
|
### Key Dependencies
|
|
|
|
- **Hyprland** — compositor (workspace switching, IPC)
|
|
- **PipeWire** — audio control (volume, mute)
|
|
- **wttr.in** — weather data (no API key needed)
|
|
- **lm_sensors** (`sensors`) — CPU temperature
|
|
- **Nerd Fonts** (GeistMono Nerd Font) — all icons are Unicode Nerd Font glyphs
|
|
- **hyprlock** / **hypridle** / **hyprshutdown** — lock, idle, power actions
|
|
|
|
## Conventions
|
|
|
|
- Icons: Nerd Font Unicode escapes (`"\u{f057e}"`) — not icon names or image files
|
|
- Colors: always reference `Shared.Theme.*` (apex-neon palette by default; apex-aeon for light mode)
|
|
- Layout: use `Shared.Theme.*` constants for sizing, spacing, radii
|
|
- Config: user-facing settings go in `Config.qml`, not hardcoded in components
|
|
- Animations: use `Behavior on <prop>` with `Shared.Theme.animFast/animNormal/animSlow`
|
|
- Inline components: `component Foo: ...` inside a file for file-local reusable types (see `SystemPopout`)
|
|
- Popout panels consume mouse clicks with a root `MouseArea` to prevent click-through closing
|