81 lines
4.5 KiB
Markdown
81 lines
4.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
A Wayland status bar for Sway/i3, written entirely in **QML** and driven by
|
|
[Quickshell](https://quickshell.outfoxxed.me/), packaged with a Nix flake.
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
# run without building (hot-reloads on file save)
|
|
nix develop # shell with quickshell + qmlls/qmlformat on PATH
|
|
quickshell --path . # or: qs -p .
|
|
|
|
nix run . # run straight from the flake
|
|
nix build . && ./result/bin/quickshell-bar # build the wrapper, then run
|
|
```
|
|
|
|
There is **no test suite, no linter, and no build step** for the QML itself —
|
|
it's interpreted and hot-reloaded. The only "build" is the Nix wrapper that
|
|
pins fonts and runtime tools. `qmlformat`/`qmlls` (from `qt6.qtdeclarative`,
|
|
available in the dev shell) are the only static tooling. Verify changes by
|
|
running the bar and looking at it.
|
|
|
|
## Architecture
|
|
|
|
**Entry point.** `shell.qml` → `ShellRoot` with `Variants { model: Quickshell.screens }`
|
|
spawns one `widgets/Bar.qml` (`PanelWindow`) per monitor. `Bar.qml` is a fixed
|
|
three-zone layout: workspaces (left), clock (center), a `RowLayout` of metric
|
|
modules (right). Changing module order/presence is purely editing that RowLayout.
|
|
|
|
**Three import roots, registered via `qmldir`:**
|
|
- `config/` — `Theme` and `Icons`, both **singletons** (`pragma Singleton` +
|
|
`singleton` line in `config/qmldir`). Global palette/geometry/fonts and Nerd
|
|
Font glyphs. Import with `import "../config"`, reference as `Theme.x` / `Icons.x`.
|
|
- `services/` — `SysStats`, a **singleton** that is the single source of truth
|
|
for all `/proc` + `/sys` metrics. Import with `import "../services"`.
|
|
- `widgets/` — the visual modules. `Pill.qml` is the rounded container every
|
|
module reuses (`default property alias content` lets children sit inside a
|
|
centered RowLayout); `MetricPill.qml` adds the icon + value convention.
|
|
|
|
**The metrics pipeline (`services/SysStats.qml`) is the core design.** One `Timer`
|
|
(1 Hz, `interval` property) calls `_tickOnce()`, which `reload()`s a set of
|
|
`FileView`s and parses them into reactive properties (`cpu`, `cpuFreq`, `mem`,
|
|
`temp`, rates, battery, …). Widgets just bind to those properties. Key conventions:
|
|
- `FileView { blockLoading: true }` makes `reload()` synchronous so `text()` is
|
|
fresh on the same tick. Use this for tiny virtual files in `/proc`/`/sys`.
|
|
- Add a metric by: declaring a property, adding a `FileView` (or reusing one by
|
|
reassigning its `path`, as `_parseNet` does for the active interface), writing
|
|
a `_parseX()`, and calling `reload()` + `_parseX()` inside `_tickOnce()`.
|
|
- Deltas (CPU%, net rates) keep a `_prev*` field and diff against the last tick.
|
|
- **Two metrics escape the pure-virtual-file rule:** disk usage runs `df` via a
|
|
`Process` only every 30 ticks (`_tick % 30`), and a one-shot `Process` runs
|
|
`services/discover.sh` at startup. The bar avoids per-tick subprocess spawns
|
|
by design — keep new metrics reading virtual files, not shelling out.
|
|
|
|
**`discover.sh` handshake.** At startup it prints `TEMP <path>` and `BAT <path>`
|
|
(hwmon temp sensor + main battery, skipping `scope=Device` peripherals) on stdout;
|
|
the QML side parses those lines into `tempPath`/`batPath`, which then feed
|
|
`FileView`s. sysfs paths are stable for a boot, so this runs once, not per tick.
|
|
|
|
## Conventions & gotchas
|
|
|
|
- **Icons are referenced by Unicode codepoint** (`config/Icons.qml`,
|
|
`String.fromCharCode(0x...)`) so source stays ASCII. The glyph **must exist in
|
|
the bundled Nerd Font** — `flake.nix` bundles `nerd-fonts.jetbrains-mono` +
|
|
`nerd-fonts.symbols-only` (Font Awesome 4 range, plus Material Design). Font
|
|
Awesome 5+ codepoints are NOT present and render as tofu squares; verify a
|
|
codepoint is covered before using it. Codepoints above `0xFFFF` (e.g. Material
|
|
Design `0xf0xxx`) need `String.fromCodePoint`, not `String.fromCharCode`.
|
|
- **Fonts are pinned via `FONTCONFIG_FILE`** in the flake wrapper, so glyphs
|
|
render regardless of the host's installed fonts. Adding a font means editing
|
|
`fontsConf` in `flake.nix`.
|
|
- **`Bar.qml` remaps its layer surface on geometry change** (`geomKey` →
|
|
toggle `visible`). This is a deliberate workaround for stale-buffer garbage
|
|
after output rotation/transform under Sway — don't remove it.
|
|
- **Quickshell upstream is tracked directly** in `flake.nix` (git, not nixpkgs)
|
|
to pick up layer-surface fixes ahead of release.
|
|
- Native Quickshell services back some modules: `Quickshell.I3` (workspaces),
|
|
`Quickshell.Services.SystemTray` (tray), PipeWire (volume).
|