Files
ricing/README.md
nico 285f87b5b7 Add install.sh, and a full dependency list to the README
install.sh clones this repo into a temp dir and moves only the paths it
tracks into ~/.config one by one, backing up anything already there under
the same name instead of overwriting it (a plain 'git clone' straight into
~/.config isn't an option - that directory already has other apps' configs
in it, and git refuses a non-empty target anyway). Re-running it detects an
existing checkout and just pulls. --dry-run previews, --deps installs
dependencies via pacman, --repo installs from a fork. Tested end to end in a
sandboxed HOME: first run (with a colliding pre-existing dir), the pull path,
and an unrelated app's config staying untouched.

README: replaced the one-line Requirements blurb with a full table (what
each program is for, pacman/apt/dnf package names) plus ready-to-paste
install commands per distro, and an Installing section pointing at the new
script.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dujsk9jYfxUVLtb5B8eC94
2026-09-28 02:08:52 +02:00

231 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ricing
My personal dotfiles for a [Hyprland](https://hyprland.org/) desktop on Arch Linux. This repo tracks only the rice-relevant configs out of `~/.config` (see [`.gitignore`](.gitignore)) — everything else in the home config directory is left untouched.
**Heads up:** the majority of this configuration — especially the entire Quickshell bar — was built with [Claude Code](https://claude.com/claude-code). I described what I wanted, reviewed the results, and iterated from there rather than hand-writing most of the QML/config myself. If you're browsing this repo for ideas, keep that in mind: it's an AI-assisted rice, not a from-scratch hand-tuned one.
## Installing
The repo is private, so grab `install.sh` with an authenticated clone rather than a raw-file `curl` (which needs a token for a private repo):
```bash
git clone https://github.com/nomminommi23/ricing.git /tmp/ricing-installer
bash /tmp/ricing-installer/install.sh # clones the repo again and drops its files into ~/.config
bash /tmp/ricing-installer/install.sh --deps # same, plus installs dependencies via pacman (Arch only)
rm -rf /tmp/ricing-installer # was only needed to get install.sh itself
```
[`install.sh`](install.sh) never runs a plain `git clone` straight into `~/.config` — that directory already has other apps' configs in it (and `git clone` refuses a non-empty target anyway). Instead it clones into a temp dir first, then moves only the paths this repo actually tracks into `~/.config` one by one; anything already there under the same name gets backed up to `~/.config-backup-<timestamp>/` rather than silently overwritten, and everything else in `~/.config` is left untouched. Re-running it later (e.g. on a machine that already has the rice) detects the existing checkout and just does a `git pull` instead. Pass `--dry-run` to see what it would do without changing anything, or `--repo=<url>` to install from a fork.
`--deps` only knows `pacman` — see [Requirements](#requirements) below for `apt`/`dnf` package lists to install by hand on other distros. Either way, log out and back into Hyprland/SDDM (or reboot) afterward.
## Stack
| Piece | Tool |
|---|---|
| Compositor | [Hyprland](https://hyprland.org/) |
| Login screen | SDDM — stock theme, not customized/tracked here (config lives under `/etc`, outside this repo's scope) |
| Bar | Custom [Quickshell](https://quickshell.org/) shell (`quickshell/default/`) — replaces Waybar entirely |
| Launcher | Rofi |
| Terminal | Kitty |
| Cursor | Custom Arch-logo cursor set (pointer, text, resize, wait spinner, …) in the rice palette — artwork in [`shapes.py`](hypr/cursor/shapes.py), [`build.py`](hypr/cursor/build.py) installs a Hyprcursor and an XCursor theme to `~/.local/share/icons/ArchLogo` |
| Notifications | [mako](mako/) — themed from the palette, same as the rest |
| Theming | [`theme/`](theme/) — homegrown palette-driven theme generator (`render.py`), controlled from the Quickshell desktop widget or the CLI |
| Qt/GTK theming | qt5ct, qt6ct, nwg-look |
| File manager | Dolphin (`kdeglobals`, `dolphinrc`) |
## The bar
Waybar has been fully retired. The whole top bar is one Quickshell shell (`quickshell/default/Bar.qml`), instantiated per monitor, laid out with real QML layouts instead of a mix of two independent renderers guessing at each other's positions. It includes:
- **Logo + workspaces** — per-monitor workspace pills (Hyprland IPC), click to switch. Click the logo itself to toggle taskbar mode (below)
- **Taskbar mode** — clicking the logo swaps the workspace pills, window title, and stat pills for a compact Windows-style taskbar of every open window, shown as icon buttons (resolved via `DesktopEntries.heuristicLookup()`, the same mechanism app launchers use, falling back to the title's first letter if no icon is found). Hover a button for the full title, click to focus. Clock and power button stay visible in both modes
- **Window switcher** — `Mod+Shift+A` drops down a list of every open window across all workspaces; click one to focus it
- **Active window title** — per-monitor, shows the title of whichever window is focused on that specific screen
- **System tray** — StatusNotifierItem icons with left-click activate / right-click context menu
- **CPU / RAM / disk / GPU** — live stats pills, each with a titled hover tooltip; click the CPU or GPU pill to toggle it between usage % and temperature (the icon stays put, only the color/value change). The disk pill defaults to `/`; click it to cycle through every real mounted filesystem (a USB stick, `/boot`, …), hovering always lists all of them with their device name (e.g. `nvme0n1p2`), used/free space and live read/write speed
- **Volume** — click opens the mixer, right-click mutes, scroll adjusts volume (via `wpctl`)
- **Network** — shows the active connection (Wi-Fi SSID or wired); hover shows the local IP (click toggles to the public IP), the network device (e.g. `enp7s0`) and the live up/download rate in decimal bit units (Kbit/Mbit/Gbit/s, like a speedtest), refreshed every second independently of the slower connection/SSID lookup
- **Clock** — hover for the full date + ISO week number, click opens a small month calendar
- **Notification panel** — the bell button (with an unread badge) opens a panel down the right screen edge, top to bottom, listing recent notifications from mako's history. Click a notification (or “Mark all read”) to mark it read and drop it from the list. mako can't delete single history entries, so read state is kept by `scripts/notifs.py` in `~/.local/state/quickshell/notifs-read`
- **Keybinds help** — in taskbar mode, a `?` button next to the clock (hover: hints what it does; click: opens a centered cheatsheet of every keybind, grouped by category). Also reachable from either mode via `Mod+Shift+H`. The list is hand-kept in sync with the Hotkeys section below — Hyprland's Lua config binds everything through one opaque `__lua` dispatcher, so `hyprctl binds` can't recover a human-readable action to auto-generate it from
- **Power menu** — restart / shutdown / logout dropdown
All the stats are pulled by small shell scripts in `quickshell/default/scripts/` rather than baked into the QML.
Hyprland itself is configured via [`hypr/hyprland.lua`](hypr/hyprland.lua) (Hyprland's Lua config API) — that's the active config; `hyprland.conf` is kept around for reference but is no longer loaded. One consequence: `hyprctl dispatch` (and anything sending it a raw dispatch string, like this bar's workspace/window-switcher clicks) needs the new `hl.dsp.*` Lua-expression syntax instead of the classic one, e.g. `hl.dsp.focus({workspace = 1})` rather than `workspace 1`.
There's also a `no_fullscreen_kitty` window rule in there working around a real Hyprland quirk: newly opened kitty windows were coming up in genuine fullscreen (`hasfullscreen: true`, not just a full-size tile) regardless of workspace, needing `fullscreen()` dispatched twice to clear. Root cause not found (no rule/config was causing it); `fullscreen_state = "0 0"` on kitty forces both the internal and client-requested state off on open. Plain `fullscreen = false` is a no-op — that's just the default, it doesn't override anything.
## Cursor
The mouse cursor is a custom theme, `ArchLogo`, with every shape redrawn in the rice style instead of only the arrow:
- **Default pointer** — the Arch logo, rotated like a classic arrow, plain accent blue without an outline. Copy / context-menu / alias / help / no-drop are the same arrow with a small badge, and the link pointer is the logo upright
- **Everything else** — text I-beam, resize arrows (edges, corners, column/row, all-direction), crosshair, cell, grab/grabbing hand, zoom, X, and a red not-allowed sign. These have a dark outline plus a light rim so they stay visible on blue or dark backgrounds
- **Animated** — `wait` is a spinning ring, `progress` is the arrow with a small spinner badge
The artwork is drawn procedurally in [`hypr/cursor/shapes.py`](hypr/cursor/shapes.py); [`hypr/cursor/build.py`](hypr/cursor/build.py) renders it (needs `rsvg-convert` and `hyprcursor-util`) into a Hyprcursor theme for Hyprland and an XCursor theme for GTK/Qt/XWayland apps, both installed to `~/.local/share/icons/ArchLogo`. Adwaita is only used as the shape/alias list and fallback. It also writes `~/.local/share/icons/default/index.theme` (`Inherits=ArchLogo`), Xcursor's fallback theme, so apps that never see `XCURSOR_THEME` (Steam and Proton games started before the env was set) get the cursor too — restart Steam once after installing. After editing `shapes.py`, run `python3 hypr/cursor/build.py` and `hyprctl setcursor ArchLogo 24`. `hyprland.lua` sets the theme via `XCURSOR_THEME` / `HYPRCURSOR_THEME` and gsettings.
## Theming
Theming used to go through a third-party app called aether; it's gone now (it didn't work reliably), replaced with a small homegrown system in [`theme/`](theme/):
- [`theme/colors.toml`](theme/colors.toml) is the single source of truth for the palette (accent, cursor, foreground/background, 16 ANSI colors)
- [`theme/templates/<app>/`](theme/templates/) holds one `{config.json, template}` pair per themed app (Hyprland, Kitty, Rofi, mako). `config.json` names the destination file; the template uses `{key}` placeholders (`{color4}`, `{background}`, `{accent}`, …), `{key.strip}` for the hex without `#`, or `{key.rgba:ALPHA}` for a `rgba(r, g, b, ALPHA)` string
- [`theme/render.py`](theme/render.py) renders every template to its destination and reloads the affected apps (`hyprctl reload`, `makoctl reload`, kitty via `SIGUSR1`). Run it after editing a template by hand, or use `--set KEY '#rrggbb'` to change one color from a terminal, `--get KEY` / `--dump` to read the palette back out
- [`theme/wallpaper.py`](theme/wallpaper.py) swaps the wallpaper: `apply <path>` archives the current one (deduped by hash) into `~/.local/share/quickshell/wallpapers/` and copies the new one to [`hypr/wallpaper.png`](hypr/wallpaper.png) (loaded via `swaybg` in `hyprland.lua`), `pick` does the same via a native file picker, `list` feeds the widget's gallery of past wallpapers
mako's per-urgency border colors (normal = accent, low = muted, critical = red) work the same way as Hyprland's border colors: edit the template at `theme/templates/mako/colors.ini`, not `mako/colors.ini` itself — that gets overwritten on the next render.
Day to day, neither script needs to be run by hand — the **theme widget**, a small standalone Quickshell window pinned to the top-left corner of the main monitor (independent of the bar), has two buttons: a picture icon opens the wallpaper gallery/picker, a paintbrush icon opens a menu to pick which color role to change and then a palette (plus a hex field) to change it to. Both call straight into the scripts above.
It's a blue theme (`#1793d1` accent on a dark `#1a1b26` background) built around the stock default Hyprland wallpaper — the anime girl waiting at the train stop with the glowing blue Hyprland-logo cats. Every accent color across the bar, Rofi, Kitty, and the rest was picked to match that wallpaper's palette rather than the other way around.
## Hotkeys
`Mod` = <kbd>Super</kbd>.
### Apps
| Key | Action |
|---|---|
| `Mod + Return` | Terminal (Kitty) |
| `Mod + W` | Browser (Zen) |
| `Mod + N` | File manager (Dolphin) |
| `Mod + Space` | App launcher (Rofi) |
| `Mod + Shift + P` | Spotify |
| `Mod + Shift + C` | Discord |
| `Mod + Shift + S` | Steam |
| `Mod + Shift + T` | btop (in terminal) |
| `Mod + Alt + C` | Qalculate |
| `Mod + C` | Clipboard history (cliphist + Rofi) |
### Bar
| Key | Action |
|---|---|
| `Mod + Shift + A` | Toggle the window switcher dropdown |
| `Mod + Shift + H` | Toggle the keybinds panel (also reachable via the taskbar-mode help button) |
### Windows
| Key | Action |
|---|---|
| `Mod + Q` | Close active window |
| `Mod + Shift + E` | Exit Hyprland |
| `Mod + F` | Toggle fullscreen |
| `Mod + V` | Toggle floating |
| `Mod + P` | Toggle pseudotiling |
| `Mod + ← / → / K / J` | Move focus (left/right/up/down) |
| `Mod + Shift + ← / → / ↑ / ↓` | Move window |
| `Mod + Ctrl + H / L / K / J` | Resize active window |
| `Mod + LMB` drag | Move window |
| `Mod + RMB` drag | Resize window |
### Workspaces
| Key | Action |
|---|---|
| `Mod + 1` … `Mod + 9` | Switch to workspace 1–9 |
| `Mod + Shift + 1` … `Mod + Shift + 9` | Move window to workspace 1–9 |
| `Mod + Scroll` | Next/previous workspace |
### Screenshots
| Key | Action |
|---|---|
| `Print` | Region screenshot → clipboard |
| `Shift + Print` | Region screenshot → `~/Pictures/Screenshots/` |
### Media / audio / brightness
| Key | Action |
|---|---|
| `XF86AudioRaiseVolume` / `LowerVolume` | Volume up/down |
| `XF86AudioMute` | Mute |
| `XF86AudioMicMute` | Mute mic |
| `XF86MonBrightnessUp` / `Down` | Brightness up/down |
| `XF86AudioPlay` / `Next` / `Prev` | Media playback control |
## Requirements
Beyond Hyprland itself, the bar's scripts expect: `quickshell`, `nmcli`, `wpctl`, `nvidia-smi` (GPU stats — no-ops gracefully if absent), `sensors` (lm_sensors, for CPU temperature), `python3`, and `curl` (for the network widget's public-IP lookup). The theme widget's wallpaper picker additionally needs `zenity` (native file picker) and `swaybg`.
This is an Arch + Hyprland rice through and through, so the list below is Arch-authoritative — everything in the pacman column is a plain `extra`/`multilib` package on current Arch, nothing needs an AUR helper. `apt`/`dnf` columns are best-effort: Hyprland and its ecosystem (Hyprland itself, `quickshell`, `hyprcursor`) move fast and generally aren't in Debian/Ubuntu's or Fedora's stock repos, so those need a third-party repo (Fedora: the [`solopasha/hyprland` COPR](https://copr.fedorainfracloud.org/coprs/solopasha/hyprland/) covers most of it) or building from source — a blank cell means "no known repo package, check the project's own install docs". Snap has essentially no coverage here (this is all system/Wayland-level tooling, not the kind of app snap packages); where an optional app happens to have one, it's noted below the table instead.
| Program | What it's for | pacman | apt | dnf |
|---|---|---|---|---|
| `hyprland` | Compositor | `hyprland` | — (COPR/build) | `hyprland` (COPR) |
| `sddm` | Login screen | `sddm` | `sddm` | `sddm` |
| `xdg-desktop-portal-hyprland` | Screen share / portals | `xdg-desktop-portal-hyprland` | — | `xdg-desktop-portal-hyprland` (COPR) |
| `quickshell` | The bar + widgets | `quickshell` | — (build) | — (build) |
| `kitty` | Terminal | `kitty` | `kitty` | `kitty` |
| `rofi` | Launcher | `rofi` | `rofi` | `rofi` |
| `mako` | Notifications | `mako` | `mako-notifier` | `mako` |
| `dolphin` | File manager | `dolphin` | `dolphin` | `dolphin` |
| `swaybg` | Wallpaper | `swaybg` | `swaybg` | `swaybg` |
| `hyprcursor` (`hyprcursor-util`) | Cursor theme build | `hyprcursor` | — | `hyprcursor` (COPR) |
| `librsvg` (`rsvg-convert`) | Cursor theme build | `librsvg` | `librsvg2-bin` | `librsvg2-tools` |
| `grim` + `slurp` | Screenshots | `grim slurp` | `grim slurp` | `grim slurp` |
| `wl-clipboard` | Clipboard (copy/paste) | `wl-clipboard` | `wl-clipboard` | `wl-clipboard` |
| `cliphist` | Clipboard history | `cliphist` | — | — (build) |
| `zenity` | Native file picker (theme widget) | `zenity` | `zenity` | `zenity` |
| NetworkManager (`nmcli`) | Network widget/pill | `networkmanager` | `network-manager` | `NetworkManager` |
| `network-manager-applet` (`nm-applet`, `nm-connection-editor`) | Network tray/settings | `network-manager-applet` | `network-manager-gnome` | `network-manager-applet` |
| WirePlumber (`wpctl`) | Volume pill | `wireplumber` | `wireplumber` | `wireplumber` |
| `pavucontrol` | Volume mixer (opened by the volume pill) | `pavucontrol` | `pavucontrol` | `pavucontrol` |
| `blueman` (`blueman-manager`) | Bluetooth manager (window rule) | `blueman` | `blueman` | `blueman` |
| `brightnessctl` | Brightness keys | `brightnessctl` | `brightnessctl` | `brightnessctl` |
| `playerctl` | Media keys | `playerctl` | `playerctl` | `playerctl` |
| `lm_sensors` (`sensors`) | CPU temperature | `lm_sensors` | `lm-sensors` | `lm_sensors` |
| `nvidia-utils` (`nvidia-smi`) | GPU stats — optional, no-ops gracefully if absent | `nvidia-utils` | `nvidia-utils-*` | `xorg-x11-drv-nvidia-cuda` |
| `curl` | Network widget's public-IP lookup | `curl` | `curl` | `curl` |
| `python3` | Bar scripts, cursor build, theme system | `python` | `python3` | `python3` |
| `qt5ct` / `qt6ct` / `nwg-look` | Qt/GTK theming | `qt5ct qt6ct nwg-look` | `qt5ct qt6ct` (nwg-look: build) | `qt5ct qt6ct` (nwg-look: build) |
| `materia-gtk-theme` | GTK theme | `materia-gtk-theme` | `materia-gtk-theme` | — (build) |
| `papirus-icon-theme` | Icon theme | `papirus-icon-theme` | `papirus-icon-theme` | `papirus-icon-theme` |
| `ttf-jetbrains-mono-nerd` | Bar/UI font | `ttf-jetbrains-mono-nerd` | — (manual install from [Nerd Fonts](https://www.nerdfonts.com/)) | — (manual install) |
```bash
# Arch (pacman - every package below is in the extra/multilib repos already
# enabled by default, no AUR helper needed)
sudo pacman -S --needed hyprland sddm xdg-desktop-portal-hyprland quickshell kitty rofi \
mako dolphin swaybg hyprcursor librsvg grim slurp wl-clipboard cliphist zenity \
networkmanager network-manager-applet wireplumber pavucontrol blueman brightnessctl \
playerctl lm_sensors nvidia-utils curl python qt5ct qt6ct nwg-look materia-gtk-theme \
papirus-icon-theme ttf-jetbrains-mono-nerd
# Debian/Ubuntu (apt) - covers everything except Hyprland/quickshell/hyprcursor/
# cliphist, which need a third-party repo or a source build on this base
sudo apt install kitty rofi mako-notifier dolphin swaybg librsvg2-bin grim slurp \
wl-clipboard zenity network-manager network-manager-gnome wireplumber pavucontrol \
blueman brightnessctl playerctl lm-sensors nvidia-utils-535 curl python3 \
qt5ct qt6ct materia-gtk-theme papirus-icon-theme sddm
# Fedora (dnf) - add the solopasha/hyprland COPR first for Hyprland/hyprcursor/
# xdg-desktop-portal-hyprland; quickshell/cliphist/nwg-look/materia-gtk-theme still need a build
sudo dnf copr enable solopasha/hyprland
sudo dnf install hyprland xdg-desktop-portal-hyprland hyprcursor kitty rofi mako dolphin \
swaybg librsvg2-tools grim slurp wl-clipboard zenity NetworkManager \
network-manager-applet wireplumber pavucontrol blueman brightnessctl playerctl \
lm_sensors xorg-x11-drv-nvidia-cuda curl python3 qt5ct qt6ct papirus-icon-theme sddm
```
**Anything not covered by a system package manager** (`quickshell`/`hyprcursor`/`cliphist` off-Arch, `nwg-look`/`materia-gtk-theme` off-Arch on Fedora): build from source per the project's own README, or check if the distro has an unofficial binary repo for it (Fedora COPR, a Debian PPA-equivalent, `chaotic-aur`-style prebuilt repos). Flatpak/Nix are worth a look for the optional apps below, but the bar/theming stack itself is system-level Wayland tooling that neither packages well.
Optional apps this config's hotkeys point at — swap the `hl.bind` targets in `hyprland.lua` for whatever you actually use instead of installing these: `zen-browser` (`Mod+W`, AUR `zen-browser-bin` on Arch; also on Flatpak as `io.github.zen_browser.zen`), `discord` (`Mod+Shift+C`, in most repos, incl. Arch `extra`; also Flatpak `com.discordapp.Discord`), `spotify` (`Mod+Shift+P`, AUR on Arch; also Flatpak `com.spotify.Client` or a Snap), `steam` (`Mod+Shift+S`, `multilib/steam` on Arch, `steam` on apt/dnf with the right repo enabled), `btop` (`Mod+Shift+T`, in most repos), `qalculate-gtk` (`Mod+Alt+C`, in most repos).
## Layout
```
hypr/ Hyprland config (hyprland.lua is active, .conf kept for reference) + wallpaper.png + cursor/ (cursor theme source)
quickshell/ The bar (Bar.qml + helper QML components + scripts/) + ThemeWidget.qml (theming widget)
rofi/ Launcher config + theme
kitty/ Terminal config + theme
mako/ Notification daemon config (colors.ini generated by theme/render.py)
theme/ Palette source (colors.toml), per-app templates, render.py + wallpaper.py
btop/ System monitor config
qt5ct/ qt6ct/ nwg-look/ gtk-3.0/ Qt/GTK theming
```