Vicious Viper

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

🖼 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.

Note

After first Neovim launch, run :MasonInstallAll to install LSP servers and formatters.

📦 Prerequisites

Important

The installer checks for these and warns about anything missing. It will not block installation unless core system utilities like cp or find are absent.

Tip

If you don't have an AUR helper, install yay first:

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

Tested On

Note

Zsh configs use ZDOTDIR=$HOME/.config/zsh. Set this before first launch:

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

Core packages

yay -S hyprland waybar foot kitty zsh rofi mako       \
        matugen-bin btop yazi fastfetch neovim starship          \
        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

Caution

Run --dry-run first on an existing setup. The installer backs up every file it will overwrite, but you should always confirm what it touches before committing.

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 (Mason, language servers)
[4] 💾  Backup all files that will be overwritten
[5] 📁  Copy selected modules into $HOME
[6] 🔑  chmod +x all scripts in ~/.local/bin/scripts
[7] 🔤  Rebuild font cache via fc-cache -f
[8] 🛤  Detect shell and optionally patch PATH
[9] 📋  Print install summary with 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.

Tip

The installer backs up everything it overwrites. If something goes wrong, run ./install.sh --uninstall to restore your originals.

📂 File Layout

$HOME
├── .config/
│   ├── hypr/             ← Hyprland compositor (Lua config)
│   ├── 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 + 20 color templates
│   ├── fastfetch/        ← System info
│   ├── cava/             ← Audio visualizer
│   ├── anyrun/           ← Alternative launcher (Rust)
│   ├── bat/              ← Cat replacement
│   ├── aerc/             ← Terminal email client (`ALT + T`)
│   ├── cmus/             ← Music player
│   ├── environment.d/    ← Environment variables
│   ├── fsh/              ← Fish shell config
│   ├── 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
│   ├── 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/chrome/          ← Zen Browser custom CSS
└── 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/

🚩 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

--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

Note

ALT is the primary modifier across the entire setup.

🎨 Theming

This setup uses Matugen — a Material You color extraction engine. Change your wallpaper, run Matugen, and Waybar, Rofi, Mako, Hyprlock, 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.jpeg

Note

Matugen templates live in .config/matugen/. Edit them to control exactly how color tokens map to each app's config format.

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/.

Note

Quickshell is in the official Arch repos (quickshell). The installer will check for it.

🌐 Zen Browser

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

Important

The installer does not copy .zen/ automatically. Apply it manually:

cp -r .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.

Crafted with 💜 by Cybersnake