Vicious Viper

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

🔮	💾	🎛	🪄	🐚
Material You theming — Matugen derives a full palette from your wallpaper and applies it to every component	Safe installer — every file that would be overwritten is backed up to a timestamped directory first	Modular installs — choose exactly which modules to deploy: configs, scripts, icons, themes, fonts, dotfiles	Dry-run mode — preview every single action without touching a single file	Shell-aware PATH patching — detects Zsh, Bash, Fish, Ksh, and falls back to POSIX `.profile`

↩️	🔤	🌐	📜	🎨
One-command undo — restore all your originals with `./install.sh --uninstall`	Bundled fonts — JetBrains Mono Nerd, Font Awesome, Icomoon Feather, Nerd Symbols — installed and cached	Zen Browser CSS — custom `userChrome.css` and `userContent.css` tuned to match the Viper aesthetic	33 custom scripts — automatically marked executable and patched into `PATH`	Live theming — change wallpaper, run matugen, everything recolors instantly

🧩 Stack

📝 Neovim

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

Component	Tool
Plugin manager	lazy.nvim
LSP	Mason — auto-installs language servers
Completion	blink.cmp
Pickers	snacks.nvim — files, grep, buffers, explorer, terminal
Treesitter	Syntax highlighting and parsing

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


🖥 OS	Arch Linux (latest)
GPU	Intel / AMD / NVIDIA (all supported via Hyprland)
🪟 Display	Wayland (Hyprland)

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

Click to expand

Package	Purpose
`xdg-desktop-portal-hyprland`	Wayland portal — screenshare, file picker
`polkit-gnome`	GUI authentication agent
`grim` + `slurp` + `wl-clipboard`	Screenshot toolchain
`brightnessctl`	Brightness control
`pavucontrol`	Audio volume GUI
`pipewire` + `pipewire-pulse` + `pipewire-alsa`	Audio stack
`wireplumber`	PipeWire session manager
`networkmanager`	Networking
`bluez` + `bluez-tools`	Bluetooth
`xorg-xwayland`	X11 app compatibility
`eza`	Better `ls`
`fd`	Better `find`
`bat`	Better `cat`
`jq`	JSON parsing (script dependency)
`libnotify`	`notify-send` — desktop notifications (script dependency)
`playerctl`	Media controls (waybar / nowplaying)
`bleachbit`	System cleaner script dependency
`neomutt`	Terminal email client (`ALT + T`)
`aerc`	Terminal email client (bundled config)
`localsend`	Local file sharing (`ALT + S`)
`nsxiv`	Image viewer (used in scripts)
`wiremix`	Audio mixer (`ALT SHIFT + P`)
`adw-gtk3` (AUR)	GTK3 theme `adw-gtk3-dark` — referenced by the GTK configs but not bundled; without it GTK apps fall back to default Adwaita. Installed by `--install-all-deps` via your AUR helper

Fonts

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

Directory	Contents
`normal-fonts/`	Comfortaa, IBM Plex Mono, JetBrainsMono, Iosevka
`nerd-fonts/`	JetBrains Mono Nerd, Fira Code Nerd, Hack Nerd, Iosevka
`icon-fonts/`	Material Icons, Icomoon Feather, Nerd Symbols, Typicons

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

_{🟥 🟨 🟢 install.sh}

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

Note

The base directory honors $XDG_DATA_HOME if set — e.g. $XDG_DATA_HOME/hypr-dotfiles-backups/.

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:

Warning

The manual steps below skip the home-path substitution the real installer performs (/home/cybersnake/... → $HOME/...). Prefer ./install.sh unless you edit the configs yourself.

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:

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

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

Set ZDOTDIR (if using Zsh with this config):

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

Reload your shell or log out and back in.
Start Hyprland: run Hyprland from a TTY or select it in your display manager.
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 (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

Flag	What it does
`--dry-run`	🔍 Preview every action — zero changes made
`--yes`	✅ Skip all confirmation prompts
`--select`	🎛 Interactively pick which modules to install
`--no-backup`	⚠️ Skip backup — also disables `--uninstall`
`--uninstall`	↩️ Restore originals from the most recent backup
`--list-backups`	📋 Show all backups with timestamps and sizes
`--install-deps`	📦 Auto-install missing Hyprland ecosystem deps
`--install-all-deps`	📦 Ecosystem + supporting packages (pipewire, bluez, grim…)
`--install-nvim-deps`	📦 Auto-install Neovim system dependencies
`--skip-deps`	🚀 Skip the ecosystem dependency check
`--version`	ℹ️ Show version and exit
`-h / --help`	📖 Show usage

# 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

Note

--install-deps, --install-all-deps, and --install-nvim-deps all install the Neovim system dependencies when the ecosystem dependency check is not skipped.

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

Shell	Line added	File patched
`zsh`	`path=(~/.local/bin $path)`	`~/.zshrc`
`bash`	`export PATH="$HOME/.local/bin:$PATH"`	`~/.bashrc`
`fish`	`fish_add_path $HOME/.local/bin`	`~/.config/fish/conf.d/hypr_path.fish`
`ksh / mksh`	`export PATH="$HOME/.local/bin:$PATH"`	`~/.kshrc`
Other	`export PATH="$HOME/.local/bin:$PATH"`	`~/.profile`

⌨️ Keybinds

Note

ALT is the primary modifier across the entire setup.

🔧 System

Keybind	Action
`F1`	Toggle mute (speakers)
`F2` / `F3`	Volume −/+ 10%
`F4`	Toggle mute (mic)
`F7`	Toggle Wi-Fi
`F9`	Lock screen
`F11` / `F12`	Brightness −/+ 10%
`Print`	Screenshot
`SUPER` + `SHIFT` + `R`	Reload Hyprland config

🚀 Apps & Launchers

Keybind	Action
`ALT` + `Enter`	Terminal (Kitty)
`ALT` + `D`	App launcher (Quickshell)
`ALT` + `R`	Yazi (TUI file manager)
`ALT` + `N`	Notifications panel
`ALT` + `I`	Toggle Dynamic Island
`ALT` + `H`	btop
`ALT` + `T`	neomutt (email)
`ALT` + `E`	Emoji picker
`ALT` + `X`	Power menu
`ALT` + `B`	Bluetooth menu
`ALT` + `L`	AirPods TUI
`ALT` + `Y`	YouTube downloader
`ALT` + `V`	Clipboard history
`ALT` + `W`	Change wallpaper
`ALT` + `K`	Kill window
`ALT` + `C`	Toggle calendar
`ALT` + `SHIFT` + `T`	Nautilus (GUI files)
`ALT` + `SHIFT` + `X`	Clear notifications
`ALT` + `SHIFT` + `P`	Audio mixer (wiremix)
`ALT` + `SHIFT` + `V`	Watch video
`ALT` + `SHIFT` + `S`	Universal snip (QuickShell)
`ALT` + `SHIFT` + `K`	System cleaner
`ALT` + `SHIFT` + `D`	aria2 downloader
`ALT` + `SHIFT` + `C`	Script editor
`ALT` + `SHIFT` + `E`	Config editor
`ALT` + `SHIFT` + `N`	Wi-Fi menu

🌐 Web shortcuts (personal — edit before use)

[!NOTE] These open personal bookmarks hardcoded in the Hyprland config. Edit them before adopting this setup — they're in .config/hypr/modules/keybinds.lua.

Keybind	Action
`ALT` + `SHIFT` + `B`	Zen Browser
`ALT` + `SHIFT` + `I`	Zen private window
`ALT` + `G`	GitHub
`ALT` + `SHIFT` + `Y`	YouTube
`ALT` + `SHIFT` + `G`	Perplexity
`ALT` + `SHIFT` + `W`	Wallhaven
`ALT` + `SHIFT` + `O`	ChatGPT
`ALT` + `SHIFT` + `R`	Reddit

🪟 Window management

Keybind	Action
`ALT` + `Q`	Close window
`ALT` + `F`	Toggle fullscreen
`ALT` + `P`	Toggle floating
`ALT` + `↑` `↓` `←` `→`	Move focus
`ALT` + `SHIFT` + `↑` `↓` `←` `→`	Swap window
`ALT` + `CTRL` + `↑` `↓` `←` `→`	Resize window
`ALT` + LMB drag	Move window
`ALT` + RMB drag	Resize window

🗂 Workspaces

Keybind	Action
`ALT` + `1–0`	Switch to workspace 1–10
`ALT` + `SHIFT` + `1–0`	Move window to workspace 1–10
`ALT` + Scroll up/down	Cycle workspaces
`ALT` + `grave`	Toggle scratchpad
`ALT` + `SHIFT` + `grave`	Move window to scratchpad

🎨 Theming

Every color, everywhere — driven by your wallpaper.

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

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:

App	App	App
Waybar	Rofi	Hyprland
Mako	Anyrun	btop
Zathura	Yazi	GTK3
GTK4	Kvantum	hyprwat
Kitty	SwayNC	SwayOSD
Zen Browser	MPV	Cava
Neovim	Foot	qt5ct
qt6ct	Quickshell	Sway
aerc	opencode

Note

SwayNC, SwayOSD, and Zathura templates are bundled, but those apps are not part of the default stack (Mako handles notifications, Quickshell handles OSD). Install them yourself if you want to use those templates.

🎛 Quickshell Panels & OSD

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

Component	Role
TopBar	Desktop panel with workspaces, clock, tray
DynamicIsland	Notification-style OSD overlays
App Launcher	Application launcher (triggered via `ALT+D`)
Lock Screen	Screen lock with clock and media controls
ClipboardViewer	Clipboard history manager
OSD	Volume/brightness on-screen display

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 .config/zen/ to match the Viper aesthetic.

File	Purpose
`.config/zen/chrome/userChrome.css`	Browser chrome — sidebar, tab bar, toolbar
`.config/zen/chrome/userContent.css`	Internal pages — new tab, `about:` pages
`.config/zen/chrome/zen-logo-mocha.svg`	Custom logo asset
`.config/zen/user.js`	Browser preferences

Important

The installer copies .config/zen/ to ~/.config/zen/, but that location is inert — Zen Browser reads its styles from your profile directory. Apply it manually:

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

Waybar / Rofi / Mako not launching

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

Scripts fail with command not found

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

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

GTK 2 theme broken after nwg-look

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

Colors didn't update after wallpaper change

matugen image /path/to/your/wallpaper

Quickshell panels / launcher not showing

# 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

Make sure quickshell is installed.

Icon glyphs showing as boxes

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

--uninstall says "No install manifest found"

The installer was never run, or the backup directory was deleted. Restore files manually from the repo tree.

Screen sharing / portals not working

# 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

Something went wrong mid-install

# 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

Navigation Menu

Repository files navigation

Vicious Viper

🖼 Preview

✨ Features

🧩 Stack

📝 Neovim

📦 Prerequisites

Tested On

Core packages

Supporting packages

Fonts

⚡ Installation

Quick start

What happens during install

Manual install (no script)

🚀 Post-Install

📂 File Layout

🚩 Installer Flags

`--select` module picker

Shell-aware PATH patching

⌨️ Keybinds

🎨 Theming

🎛 Quickshell Panels & OSD

🌐 Zen Browser

🔄 Updating

🔧 Troubleshooting

🔐 Security

🤝 Contributing

💬 Getting Help

📄 License

About

Releases

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.config		.config
.fonts		.fonts
.github/workflows		.github/workflows
.icons		.icons
.local/bin/scripts		.local/bin/scripts
.themes		.themes
assets		assets
etc		etc
.Xresources		.Xresources
.gitignore		.gitignore
.gtkrc-2.0		.gtkrc-2.0
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh

Latest commit

History

Folders and files

Repository files navigation

Vicious Viper

🖼 Preview

✨ Features

🧩 Stack

📝 Neovim

📦 Prerequisites

Tested On

Core packages

Supporting packages

Fonts

⚡ Installation

Quick start

What happens during install

Manual install (no script)

🚀 Post-Install

📂 File Layout

🚩 Installer Flags

--select module picker

Shell-aware PATH patching

⌨️ Keybinds

🎨 Theming

🎛 Quickshell Panels & OSD

🌐 Zen Browser

🔄 Updating

🔧 Troubleshooting

🔐 Security

🤝 Contributing

💬 Getting Help

📄 License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages

`--select` module picker