Vicious Viper

A wallpaper-synced Hyprland rice for Arch Linux.
Material You theming · Automated backups · Modular installer · Clean daily workflow.

📖 Table of Contents

🖼 Preview · ✨ Features · 🧩 Stack · 📝 Neovim
📦 Prerequisites · ⚡ Installation · 🚀 Post-Install
📂 Layout · 🚩 Flags · ⌨️ Keybinds
🎨 Theming · 🎛 Quickshell · 🌐 Zen
🔄 Updating · 🔧 Troubleshoot · 🔐 Security · 🤝 Contributing · 📄 License

🖼 Preview

✨ Features

🧩 Stack

📝 Neovim

The Neovim config (.config/nvim/) is a modern Lua-based setup:

System dependencies (--install-nvim-deps): wl-clipboard, python, imagemagick, luarocks, shellcheck, gcc, nodejs, npm.

📦 Prerequisites

sudo pacman -S --needed git base-devel
git clone https://aur.archlinux.org/yay.git /tmp/yay
cd /tmp/yay && makepkg -si

Tested On

echo 'export ZDOTDIR="$HOME/.config/zsh"' > ~/.zshenv

Core packages

yay -S hyprland hyprlock hyprpaper waybar foot kitty zsh rofi mako \
        matugen-bin awww-git btop yazi fastfetch neovim starship fontconfig \
        cava cmus mpv nautilus zen-browser-bin aria2 advcpmv \
        quickshell hyprwat

Supporting packages

Fonts

The .fonts/ directory is bundled and installed automatically. It is organized into three subdirectories:

To install manually:

yay -S ttf-jetbrains-mono-nerd ttf-font-awesome nerd-fonts-symbols-only
fc-cache -f

⚡ Installation

Quick start

git clone https://github.com/Cybersnake223/Hypr
cd Hypr
chmod +x install.sh
./install.sh --dry-run   # preview first
./install.sh             # install when ready

What happens during install

[1] ✅  Verify core system utilities
[2] 🔍  Check Hyprland ecosystem packages
[3] 📦  Check Neovim system dependencies
[4] 💾  Backup all files that will be overwritten
[5] 📁  Copy selected modules into $HOME
[6] 🔑  chmod +x all scripts
[7] 🔤  Rebuild font cache (fc-cache -f)
[8] 🛤  Detect shell, patch PATH
[9] 📋  Print install summary + log path

Backups land here:

~/.local/share/hypr-dotfiles-backups/<YYYYMMDD-HHMMSS>/

Each backup contains a .manifest of every installed path — used by --uninstall to restore precisely.

Manual install (no script)

The installer is just a Bash script — review it, then replicate manually:

for dir in .config .icons .themes .fonts; do
  [ -d "$dir" ] && cp -r "$dir" "$HOME/"
done
[ -d .local/bin/scripts ] && cp -r .local/bin/scripts "$HOME/.local/bin/"
for f in .Xresources .gtkrc-2.0; do
  [ -f "$f" ] && cp "$f" "$HOME/"
done

# Copy Quickshell QML configs separately
[ -d .config/quickshell ] && cp -r .config/quickshell "$HOME/.config/"
[ -d .config/matugen ] && cp -r .config/matugen "$HOME/.config/"
[ -f .config/qt5ct/qt5ct.conf ] && mkdir -p "$HOME/.config/qt5ct" \
  && cp .config/qt5ct/qt5ct.conf "$HOME/.config/qt5ct/"

find "$HOME/.local/bin/scripts" -type f -exec chmod +x {} +
fc-cache -f
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# Start Quickshell panels
~/.config/hypr/scripts/qs_manager.sh &

🚀 Post-Install

After the installer finishes:

1. Enable system services (if this is a fresh Arch install):

   systemctl --user enable --now pipewire pipewire-pulse wireplumber
   sudo systemctl enable --now bluetooth networkmanager
   

2. Set ZDOTDIR (if using Zsh with this config):

   echo 'export ZDOTDIR="$HOME/.config/zsh"' > ~/.zshenv
   

3. Reload your shell or log out and back in.
4. Start Hyprland: run Hyprland from a TTY or select it in your display manager.
5. Run :MasonInstallAll inside Neovim on first launch to install LSP servers and formatters.

📂 File Layout

$HOME
├── .config/
│   ├── hypr/             ← Hyprland (Lua config; hyprlock, hypridle, hyprpaper)
│   ├── waybar/           ← Status bar
│   ├── quickshell/       ← QML panels, launcher, OSD, lock screen
│   ├── rofi/             ← App launcher
│   ├── nvim/             ← Neovim (Lua, lazy.nvim)
│   ├── zsh/              ← Zsh (uses $ZDOTDIR)
│   ├── kitty/            ← Kitty terminal
│   ├── foot/             ← Foot terminal
│   ├── mako/             ← Notifications
│   ├── yazi/             ← TUI file manager
│   ├── mpv/              ← Media player
│   ├── btop/             ← System monitor
│   ├── matugen/          ← Matugen config + 28 color templates
│   ├── fastfetch/        ← System info
│   ├── starship.toml     ← Prompt
│   ├── cava/             ← Audio visualizer
│   ├── anyrun/           ← Alternative launcher (Rust)
│   ├── bat/              ← Cat replacement
│   ├── aerc/             ← Terminal email client (bundled config)
│   ├── cmus/             ← Music player
│   ├── environment.d/    ← Environment variables
│   ├── fsh/              ← fast-syntax-highlighting theme (Zsh, via `fast-theme`)
│   ├── gtk-2.0/          ← GTK2 theme
│   ├── gtk-3.0/          ← GTK3 CSS (Matugen-recolored)
│   ├── gtk-4.0/          ← GTK4 CSS (Matugen-recolored)
│   ├── hyprwat/          ← Wallpaper picker GUI
│   ├── Kvantum/          ← Qt theme engine
│   ├── qt5ct/            ← Qt5 settings
│   ├── qt6ct/            ← Qt6 settings
│   ├── zen/              ← Zen Browser CSS — NOT installed; applied to ~/.zen/chrome manually (see Zen section)
│   ├── xsettingsd/       ← X settings daemon (GTK theming bridge)
│   ├── yay/              ← AUR helper config
│   └── ...
├── .local/bin/scripts/   ← 33 custom shell scripts
├── .fonts/               ← Bundled fonts
├── .icons/               ← Icon theme
├── .themes/              ← GTK/Qt themes
├── .Xresources
├── .gtkrc-2.0
├── .zen/                 ← Zen Browser profile (custom CSS copied here manually — see Zen section)
└── assets/               ← Screenshots and logo

/etc/ (system-level — not installed, apply manually):
├── auto-cpufreq.conf    ← CPU governor tuning
├── pacman.conf          ← Pacman parallel downloads + eye candy
└── pacman.d/

> ⚠️ **Security notes:** `etc/pacman.conf` sets `SigLevel = Optional TrustAll`, which
> disables package signature verification — convenient on a personal machine but not
> recommended to copy verbatim. `.config/environment.d/zen.conf` sets
> `MOZ_DISABLE_RDD_SANDBOX=1`, which disables Firefox's media-decoder sandbox to
> allow hardware video decode; a known tradeoff between security and performance.

🚩 Installer Flags

# Full install with all dependencies (recommended for first-timers)
./install.sh --install-all-deps --yes

# First-timer recommended flow (preview before committing)
./install.sh --dry-run

# Standard install
./install.sh

# Non-interactive (CI / scripted)
./install.sh --yes --skip-deps

# Pick only what you want
./install.sh --select

# Undo the last install
./install.sh --uninstall

# See all saved backups
./install.sh --list-backups

# Show installer version
./install.sh --version

--select module picker

[✓]  1  .config       Application configs (hypr, waybar, rofi, nvim, zsh…)
[✓]  2  scripts       Custom scripts → ~/.local/bin/scripts
[ ]  3  .icons        Icon theme
[✓]  4  .themes       GTK/Qt themes
[✓]  5  .fonts        Custom fonts (triggers fc-cache rebuild)
[✓]  6  dotfiles      Root dotfiles (.Xresources, .gtkrc-2.0)

Toggle a number, press Enter to confirm.

Shell-aware PATH patching

⌨️ Keybinds

🎨 Theming

_{The palette is derived live from your wallpaper.}

This setup uses Matugen — a Material You color extraction engine. Change your wallpaper, run Matugen, and Waybar, Rofi, Mako, GTK apps, and the terminal all recolor automatically.

Use hyprwat for a GUI wallpaper picker that triggers Matugen recolor on selection.

# Set wallpaper and regenerate palette
aww set /path/to/wallpaper.jpg
matugen image /path/to/wallpaper.jpg

# Force a refresh from the cached wallpaper
matugen image ~/.config/hypr/wallpaper/current.png

Templates are provided for these components:

🎛 Quickshell Panels & OSD

This setup uses Quickshell as the core UI framework, providing a QML-based desktop shell that powers several visual components:

Quickshell processes are auto-started by qs_manager.sh on Hyprland startup. The config files live under .config/quickshell/.

🌐 Zen Browser

Custom styling for Zen Browser is included under .config/zen/ to match the Viper aesthetic.

cp -r .config/zen/chrome "$HOME/.zen/chrome"

Then enable custom CSS in about:config:

toolkit.legacyUserProfileCustomizations.stylesheets = true

Restart Zen. If your profile is not at ~/.zen/ (e.g. Flatpak installs use ~/.var/app/), find the correct path via about:support → Profile Directory.

🔄 Updating

git pull
./install.sh --dry-run   # preview what changed
./install.sh             # apply

Each run creates a fresh backup. To roll back after an update:

./install.sh --uninstall      # restore most recent backup
./install.sh --list-backups   # or inspect all available backups

🔧 Troubleshooting

./install.sh --dry-run
which hyprland waybar rofi mako matugen kitty foot zsh

# Zsh
echo 'path=(~/.local/bin $path)' >> ~/.zshrc
source ~/.zshrc

# Bash / others
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

cp /path/to/Hypr/.gtkrc-2.0 ~/.gtkrc-2.0

matugen image /path/to/your/wallpaper

# Check if quickshell is installed
which quickshell

# Verify qs_manager.sh is running
pgrep -f "qs_manager" || ~/.config/hypr/scripts/qs_manager.sh

# Check the install log for errors
tail -30 /tmp/hypr-install-*.log 2>/dev/null

yay -S ttf-font-awesome nerd-fonts-symbols-only
fc-cache -f

# Make sure xdg-desktop-portal-hyprland is installed
yay -S xdg-desktop-portal-hyprland

# Restart the portal service
systemctl --user restart xdg-desktop-portal-hyprland

# Check service status
systemctl --user status xdg-desktop-portal-hyprland

# Show the last 50 lines of the most recent install log
tail -50 /tmp/hypr-install-*.log 2>/dev/null

🔐 Security

Do not open a public GitHub issue for vulnerabilities. See SECURITY.md for responsible disclosure.

🤝 Contributing

PRs are welcome for fixes, improvements, and documentation updates. Include screenshots when UI is affected.

💬 Getting Help

Need help or have questions? Start a discussion:

• GitHub Discussions — ask questions, share setups, get help

For bugs and issues, use the Issue Tracker.

📄 License

MIT — see LICENSE for details.

Enjoying Vicious Viper? Give it a ⭐!

Crafted with 💜 by Cybersnake