HyprFlow-Arch

Complete Hyprland + Arch Linux configuration optimized for technical productivity on desktop, with multi-monitor support, Logitech/Apple peripherals, and automated dynamic theming.

Compatibility

Note: Hyprland 0.55 is migrating configuration to .lua. This repo targets the .conf format and is tested with the versions below. A pre-lua-migration tag marks this checkpoint.

Tool	Version
Hyprland	0.54.3
Waybar	0.15.0
eww	0.6.0
swaync	0.12.6
wallust	3.5.2
rofi-wayland	2.0.0

Key Features

• Automated install — one script copies configs, creates symlinks, and applies the base theme
• Dynamic theming — color palettes auto-generated with wallust on wallpaper change, synced to cava visualizer
• Master layout — main window takes priority, secondary windows stack on the side
• 3-monitor management — automatic logical mapping via monitors.sh, configurable layout (4 with ThinkPad)
• Peripheral battery in Waybar — mouse, keyboard, trackpad, and headset in real time
• Status modules — VPN, camera, microphone, audio, and DND notifications integrated

Table of Contents

• Preview
• Hardware & Peripherals
• Installation
• Included Scripts
• Post-Installation
• Hyprland Plugins
• Tips

Preview

Hardware & Peripherals

Setup designed for the following peripherals, with integrated battery monitoring:

Peripheral	Model
Mouse	Logitech MX Master 3S
Keyboard	Logitech MX Keys S
Trackpad	Apple Magic Trackpad

Monitor Layout

Primary desktop setup with 3 monitors. The logical mapping is defined in monitors_ids.conf (auto-generated). Current layout left to right:

Position	Monitor	Resolution
1	AOC	1080p
2	NZXT (Primary)	1440p @ 120Hz
3	ASUS	1080p

When connecting the ThinkPad it joins as a 4th monitor (eDP-1).

Installation

1. Install dependencies

Official repositories:

sudo pacman -S cpio cmake fzf rtkit hyprland waybar yazi kitty awww brightnessctl playerctl pipewire wireplumber pipewire-pulse pavucontrol network-manager-applet upower openconnect jq pacman-contrib swaync hyprshot hyprpicker rofi-wayland ttf-jetbrains-mono-nerd noto-fonts-cjk wl-clipboard satty gnu-free-fonts gnome-themes-extra xdg-desktop-portal xdg-desktop-portal-gtk xdg-desktop-portal-hyprland gnome-disk-utility polkit-gnome cava

AUR (requires yay or another helper):

yay -S wlogout eww-git waypaper-git wallust headsetcontrol bibata-cursor-theme-bin paru zsh-fzf-tab oh-my-zsh-git

2. Clone and install

This repo uses Git submodules (Rofi themes, trackpad-battery, sinkswitch). Clone with --recursive:

git clone --recursive https://github.com/AlejandroMinor/HyprFlow-Arch.git
cd HyprFlow-Arch
bash install.sh

If you want to skip applying the default theme and color palettes (e.g. reinstalling while keeping your current theme), use the --skip-theme flag:

bash install.sh --skip-theme

If you already cloned without --recursive:

git submodule update --init --recursive

The install script handles:

• Setting execute permissions on all .sh and .py scripts
• Copying configuration to ~/.config
• Creating symlinks for binaries in ~/.local/bin
• Applying the default color palette
• Reloading Hyprland and plugins

3. First steps

Run help-binds.sh or press Super + I to see all available keybindings:

help-binds.sh

Included Scripts

All scripts in bin/ are available globally in ~/.local/bin after installation.

Theming

Script	Description
wallust-theme-manager.sh	Generates dynamic color palettes and applies themes
theme-picker.sh	Interactive theme selector with pre-designed color palettes

Monitors & Layout

Script	Description
monitors.sh	Detects monitors and creates the mapping in monitors_ids.conf
session-manager/	Suite for saving and restoring window layouts (save, load, restore, snapshot)

Waybar Status Modules

Script	Description
mute_indicator.sh	Microphone status indicator
vpn_status.sh	VPN connection status
peripherals_battery.sh	Peripheral battery levels (mouse, keyboard)
g733_battery.sh	Logitech G733 headset battery
trackpad-battery	Apple Magic Trackpad battery
camera_status.py	Camera-in-use indicator
swaync-dnd.sh	Do Not Disturb control for SwayNC
battery_alert.py	Low system battery alert
cava-waybar.sh	Cava audio visualizer output for Waybar (hides when silent)

Utilities

Script	Description
help-binds.sh	Shows all keybindings in a visual interface
hyprland-group-all.sh	Groups all windows in the current workspace
kb-layout-toggle.sh	Toggles keyboard layout
sinkswitch	Quick audio output switcher

Included submodules:

• modules/rofi-collection — collection of Rofi themes, applets, and launchers
• modules/apple-magic-trackpad-battery — trackpad battery script
• modules/sinkswitch — audio output switching utility

Post-Installation

Zsh + Oh My Zsh (optional)

A separate script is included if you want to use the same Zsh setup. It backs up your existing .zshrc before overwriting.

Dependencies:

# Official repos
sudo pacman -S zsh zsh-autosuggestions zsh-syntax-highlighting zoxide bat

# AUR
yay -S fzf-tab oh-my-zsh-git

Install:

bash install-zsh.sh

Plugins included:

Plugin	Source	Description
git sudo copypath fzf	Oh My Zsh built-in	Git aliases, sudo escape, clipboard, fzf integration
zsh-autosuggestions	Official repos	Command suggestions from history
zsh-syntax-highlighting	Official repos	Real-time command highlighting
fzf-tab	AUR (fzf-tab)	Tab completion with fzf preview using bat
zoxide	Official repos	Smart cd replacement (z, zi)

Dark theme

To force dark colors for GTK apps:

gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'
gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'
gsettings set org.gnome.desktop.interface icon-theme 'Adwaita'

Magic Trackpad (optional)

For the trackpad battery module to work correctly, see the full setup guide (permissions, groups, and security options) in the submodule README:

apple-magic-trackpad-battery/README.md

Theming with Waypaper (recommended)

In ~/.config/waypaper/config.ini, enable zen_mode and set the post_command to regenerate the palette on wallpaper change:

[Settings]
backend = awww
fill = fill
zen_mode = True
post_command = bash -c "$HOME/HyprFlow-Arch/bin/wallust-theme-manager.sh --generate-palette --notify"

To restore or change the color palette, use the interactive theme picker:

theme-picker.sh

Or manually restore the default theme:

wallust cs ~/HyprFlow-Arch/wallust/themes/minor-default.json
~/HyprFlow-Arch/bin/wallust-theme-manager.sh --restore-default --notify

Cava audio visualizer

Cava is integrated in two ways: as a terminal visualizer and as a Waybar center module. Colors sync automatically with the active wallust theme — the palette is regenerated each time wallust runs and saved to ~/.config/cava/themes/wallust.

Terminal:

cava

Waybar: the custom/cava module runs cava-waybar.sh, which displays block-character bars in the center of the bar next to the media info. It hides automatically when there is no audio.

Static themes solarized_dark and tricolor are available in ~/.config/cava/themes/ as fallbacks.

Hyprland Plugins

Install and manage plugins with hyprpm:

hyprpm update
hyprpm add https://github.com/hyprwm/hyprland-plugins
hyprpm enable <plugin-name>

Currently active plugins:

Plugin	Description
hyprfocus	Enhanced window focus animation
hyprwinwrap	Embed apps directly as desktop background
hymission	macOS-style Mission Control window overview, install via hyprpm add https://github.com/gfhdhytghd/hymission

Note: If errors about animations or invalid references appear on startup, the plugins are likely outdated relative to the installed Hyprland version. Run:

hyprpm update

Tips

• Waybar + monitors: If Waybar doesn't appear correctly, check dotconfig/hypr/monitors_ids.conf and adjust the IDs. monitors.sh fixes it in most cases, but some setups may require manual adjustment in dotconfig/waybar/config.
• Monitor mapping: If you add or change monitors, regenerate the logical mapping with monitors.sh. You can also reload Hyprland with hyprctl reload to pick up the new configuration.
• Sessions: session-manager/save.sh saves the current layout; restore.sh restores it. Both are available as keybindings.
• DisplayLink: Install displaylink and evdi-dkms-git from AUR (yay -S displaylink evdi-dkms-git), then enable the service with sudo systemctl enable --now displaylink.service.
• Permissions: If a script won't run, chmod +x script_name. install.sh sets them automatically.