Hyprland / Quickshell setup
Files
README.md

tsubasa #

Hyprland + Quickshell setup: bar, launcher, notifications, OSD, overview, power menu, theme switcher, wallpaper picker and monitor manager. Adwaita-dark GTK, Yaru-purple icons and macOS-style font rendering.

Not tied to a distro: install the packages below with your package manager, then run install.sh.

Incorporates run-or-raise, agent status dots on workspaces (supports CC + Codex + OC + Crush + pi), webapp installation from the launcher, widgets for Bluetooth / WiFi and a notification centre.

Screenshots #

Desktop, tiling, launcher

Layout #

config/<name>/           → ~/.config/<name>
config/quickshell/doannc → ~/.config/quickshell/doannc  (state files stay outside the repo)
home/                    → ~/.bashrc, ~/.bash_profile
bin/                     → ~/.local/bin
sddm/                    optional login screen theme config (see extras.sh sddm_theme)
install.sh               symlinks + GTK settings; safe to rerun
extras.sh                user-level builds of things many distros don't package; safe to rerun

install.sh moves anything already at a target aside to <name>.pre-dotfiles.

Install #

  1. Packages. Names vary by distro; install what yours calls these.

    For Packages
    Desktop hyprland (with Lua config support), xdg-desktop-portal-hyprland, xdg-desktop-portal-gtk, hyprlock, hypridle, hyprpolkitagent, hyprpaper, hyprpicker, hyprsunset
    Shell quickshell (0.3+, with Quickshell.Networking), Qt 6 wayland/declarative/multimedia/svg, jq, NetworkManager, pipewire + wireplumber, bluez
    Tools grim, slurp, wl-clipboard, playerctl, brightnessctl, libnotify (notify-send), alacritty, nautilus
    Look adw-gtk3, Yaru icon theme, Ubuntu fonts, Verdana (MS core fonts), Noto Sans / CJK / Color Emoji, Nerd Font symbols, M+ Nerd Font
    Optional matugen or wallust (colours from wallpaper), satty (screenshot editor), ble.sh, sddm + sddm-astronaut-theme

    Anything missing from your distro, ./extras.sh can fetch or build into $HOME (matugen and satty need cargo and the GTK 4 / libadwaita headers).

  2. Link the config

    git clone <this repo> ~/dotfiles && cd ~/dotfiles
    ./install.sh
    ./extras.sh                # or just the pieces you need: ./extras.sh adw_gtk3 mplus_font
    ./extras.sh sddm_theme     # optional: login screen that follows the wallpaper (sudo)
    
  3. Log in to Hyprland from your display manager (or run start-hyprland from a tty). Outputs are auto-placed and auto-scaled, the theme is Pure, and there's no wallpaper until you pick one with SUPER + SHIFT + W (it lists ~/Pictures/Wallpapers). Arrange monitors with SUPER + O. SUPER + K lists every binding.

Making it yours #

  • Apps: the top of config/hypr/bindings.lua. The browser binding and bin/webapp-install assume brave-origin; change them to your browser.
  • Per machine: ~/.config/hypr/monitors.lua is written by the monitor manager and not tracked. Hardware extras (input devices, switches, a fixed scale) go in hosts/<hostname>/hypr.lua, which hyprland.lua loads if it exists.
  • Theme and wallpaper: SUPER + SHIFT + T and SUPER + SHIFT + W. The choice lives in ~/.config/quickshell/, outside the repo.
  • GTK settings (dark, accent, fonts, cursor, icons) are the gsettings lines at the end of install.sh.

Helpers in bin/ #

Script Does
run-or-raise <class-re> <cmd…> Focus a matching window (cycles on repeat), else launch it
webapp-install [name] [url] [icon] Make a Brave --app launcher that uses run-or-raise
webapp-remove [name…] Remove one
nightlight Toggle hyprsunset (scheduled 21:00–07:00 by config/hypr/hyprsunset.conf)
restart-hyprsunset Restart hyprsunset after suspend, so its schedule applies again
lid-panel close|open Turn the built-in panel (eDP-) off when the lid closes and another output is on
lock-screen, lock-before-sleep hypridle's lock commands; wait for the compositor to confirm the lock
term-wait <cmd> Run a command, keep the terminal open until a key press