Auto-detected monitor configuration (works with any setup out of the box)
Workspaces 1-4 on external monitor, 5-10 on laptop screen
Monitor handler - automatically restores wallpaper and Caelestia shell after config reload

Automation

Auto-installer - interactive Python installer handles the entire setup
Waypaper hook - pywal colors auto-apply when wallpaper changes via waypaper GUI
Monitor handler - listens for Hyprland config reloads and restarts swaybg/Caelestia
Fastfetch config - custom system info display with ASCII art

Quick Install

curl -fsSL https://raw.githubusercontent.com/duma799/hyprduma-config/master/install.sh | bash

Or manually:

git clone https://github.com/duma799/hyprduma-config.git ~/Downloads/hyprduma-config
python3 ~/Downloads/hyprduma-config/install.py

The interactive installer handles everything:

AUR helpers (yay/paru)
Required packages via pacman
Caelestia shell
Config backup and installation
Pywal integration (templates, scripts, bashrc, initial colors)
Waypaper hook for automatic color application
Monitor handler for config reload resilience
Fastfetch config with custom ASCII art

Manual Installation Guide

If you prefer to install manually instead of using the auto-installer, follow these steps.

Prerequisites: Install AUR Helpers (Optional but Recommended)

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

# Install paru
git clone https://aur.archlinux.org/paru.git
cd paru && makepkg -si && cd .. && rm -rf paru

Step 1: Install Required Packages

sudo pacman -S hyprland hyprlock hyprshot wlogout kitty waybar swaybg waypaper wofi nautilus wireplumber pipewire-pulse brightnessctl playerctl adwaita-cursors python-pywal fastfetch

Step 2: Install Caelestia Shell (Recommended)

yay -S caelestia-shell

Step 3: Clone and Install Config

cd ~/Downloads
git clone https://github.com/duma799/hyprduma-config.git
cd hyprduma-config

# Backup existing configs
[ -d ~/.config/hypr ] && mv ~/.config/hypr ~/.config/hypr.backup
[ -d ~/.config/waybar ] && mv ~/.config/waybar ~/.config/waybar.backup
[ -d ~/.config/wlogout ] && mv ~/.config/wlogout ~/.config/wlogout.backup

# Install Hyprland config
mkdir -p ~/.config/hypr
cp hyprland.conf ~/.config/hypr/
cp -r wallpapers ~/wallpapers
mkdir -p ~/Pictures/Screenshots

Step 4: Install Scripts

# Copy all scripts
mkdir -p ~/.config/hypr/scripts
cp pywal.sh sync-caelestia-wallpaper.sh waypaper-hook.sh ~/.config/hypr/scripts/
cp monitor-handler.py ~/.config/hypr/scripts/
chmod +x ~/.config/hypr/scripts/*.sh

# Note: The script aliases 'pywal' to ~/.config/hypr/scripts/pywal.sh
# To set it up manually: echo "alias pywal='~/.config/hypr/scripts/pywal.sh'" >> ~/.bashrc

Step 5: Configure Your Applications

Edit ~/.config/hypr/hyprland.conf and adjust the app variables (lines 28-34):

$terminal = kitty
$fileManager = nautilus
$menu = wofi --show drun
$telegram = Telegram
$spotify = spotify
$vscode = code
$browser = your-browser

Step 6: Install Pywal Integration

# Install pywal templates
mkdir -p ~/.config/wal/templates
cp -r wal/templates/* ~/.config/wal/templates/

# Setup Kitty terminal
mkdir -p ~/.config/kitty
cp kitty/kitty.conf ~/.config/kitty/

# Add pywal to bashrc
cat >> ~/.bashrc << 'EOF'

# Import pywal colorscheme from cache
(cat ~/.cache/wal/sequences &)

# To add support for TTYs (optional)
source ~/.cache/wal/colors-tty.sh 2>/dev/null
EOF

# Generate initial colors
wal -i ~/wallpapers/sakura.jpg && pywal
source ~/.bashrc

Step 7: Configure Waypaper Hook

The waypaper hook automatically applies pywal colors whenever you change wallpaper through the waypaper GUI.

# Set waypaper-hook.sh as waypaper's post_command
mkdir -p ~/.config/waypaper
# Add to ~/.config/waypaper/config.ini under [Settings]:
# post_command = ~/.config/hypr/scripts/waypaper-hook.sh

Step 8: Install Fastfetch Config (Optional)

cp -r fastfetch ~/.config/fastfetch

# Fix hardcoded paths for your user
sed -i "s|/home/duma/|$HOME/|g" ~/.config/fastfetch/config.jsonc

Step 9: Start Hyprland

# From TTY
Hyprland

# Or if already running, reload config
# Press SUPER + SHIFT + R

Post-Installation

Setting Wallpaper

Using waypaper GUI (recommended):

Press Super+W to open waypaper
Select a wallpaper - the waypaper hook automatically runs pywal and syncs colors to all components (Hyprland, Caelestia, Kitty, GTK, Firefox)

Using command line:

wal -i /path/to/wallpaper.png && pywal

How wallpaper management works:

swaybg is the wallpaper backend (not hyprpaper)
waypaper GUI sets the wallpaper and triggers waypaper-hook.sh as a post-command
The hook runs pywal, syncs Caelestia colors/wallpaper, reloads Hyprland, and updates GTK/Firefox themes
sync-caelestia-wallpaper.sh syncs Caelestia's wallpaper reference with swaybg on startup
monitor-handler.py listens for config reloads and restores swaybg/Caelestia if they get killed

System-Wide Theme Syncing

The pywal.sh script supports dark/light mode and system-wide theme synchronization (GTK, Firefox, Qt). See PYWAL-SETUP.md for the full guide including optional enhancements, light/dark theme switching, and backend options.

pywal ~/Pictures/wallpaper.jpg          # Dark theme (default)
pywal ~/Pictures/wallpaper.jpg light    # Light theme
pywal "" dark                            # Switch mode, keep wallpaper
pywal                                    # Refresh current theme

Monitor Configuration

The default config uses auto-detection which works with any monitor setup:

monitor = , preferred, auto, 1

To customize for specific monitors, edit ~/.config/hypr/hyprland.conf (line 4):

# Example: dual monitor with specific resolution
monitor = eDP-1, 1920x1080@144, 1920x0, 1
monitor = HDMI-A-1, 1920x1080@144, 0x0, 1, transform, 2

Workspace assignment (lines 7-17) distributes workspaces 1-4 to the external monitor and 5-10 to the laptop screen.

Monitor Handler

The monitor-handler.py script runs in the background and listens for Hyprland config reloads. When a reload is detected, it checks if swaybg and Caelestia are still running, and restarts them if needed. This prevents losing your wallpaper or shell after editing the config.

Keyboard Layout

Default is US/RU with ALT+SHIFT toggle. To change, edit the input section in ~/.config/hypr/hyprland.conf:

kb_layout = us, ru  # Change to your layouts

Project Structure

hyprduma-config/
├── hyprland.conf              # Main Hyprland configuration
├── pywal.sh                   # Apply pywal colors to all components
├── waypaper-hook.sh           # Auto-apply colors on wallpaper change
├── sync-caelestia-wallpaper.sh # Sync swaybg wallpaper to Caelestia
├── monitor-handler.py         # Restart wallpaper/shell after config reload
├── install.py                 # Interactive auto-installer
├── install.sh                 # Curl one-liner bootstrap script
├── wallpapers/                # Included wallpapers
├── wal/templates/             # Pywal templates for Hyprland & Caelestia
├── kitty/kitty.conf           # Kitty terminal config with pywal support
├── fastfetch/                 # Custom fastfetch config with ASCII art
├── KEYBINDS.md                # Complete keybindings reference
└── PYWAL-SETUP.md             # Detailed pywal integration guide

Documentation

KEYBINDS.md - Complete keybindings reference
PYWAL-SETUP.md - Detailed pywal integration guide

Troubleshooting

Hyprland won't start

Check if all required packages are installed
Review error logs: journalctl -b | grep hyprland

Applications don't launch

Make sure you edited the app variables in hyprland.conf (lines 28-34)
Check if the applications are actually installed

Pywal colors not applying

If colors work in Hyprland but not in terminals/shell:

Check if templates are installed:

ls ~/.config/wal/templates/
# Should show: hyprland-colors.conf, caelestia-scheme.json

If missing, copy them:

mkdir -p ~/.config/wal/templates
cp ~/.config/hypr/wal/templates/* ~/.config/wal/templates/

Regenerate colors:
```
wal -R && pywal
```

Check bash configuration:

grep -A 5 "pywal" ~/.bashrc

If missing, add:

cat >> ~/.bashrc << 'EOF'

# Import pywal colorscheme from cache
(cat ~/.cache/wal/sequences &)

# To add support for TTYs (optional)
source ~/.cache/wal/colors-tty.sh 2>/dev/null
EOF

source ~/.bashrc

Check Kitty configuration:

grep "colors-kitty" ~/.config/kitty/kitty.conf

Should show: include ~/.cache/wal/colors-kitty.conf

If it shows kitty-colors.conf (wrong filename), fix it:

sed -i 's/kitty-colors.conf/colors-kitty.conf/g' ~/.config/kitty/kitty.conf
killall -SIGUSR1 kitty  # Reload kitty

Verify pywal cache files exist:

ls ~/.cache/wal/hyprland-colors.conf
ls ~/.cache/wal/colors-kitty.conf
ls ~/.cache/wal/sequences

General pywal troubleshooting:

Ensure the script is executable: chmod +x ~/.config/hypr/scripts/pywal.sh
Check if pywal cache exists: ls ~/.cache/wal/
Manually reload: pywal

Caelestia colors not updating

# Restart Caelestia daemon
pkill caelestia && sleep 0.5 && caelestia shell -d &

Wallpaper not showing after config reload

The monitor handler should restore it automatically. If not:

# Check if monitor-handler is running
pgrep -f monitor-handler.py

# Restart it if needed
python3 ~/.config/hypr/monitor-handler.py &

# Or manually restore
waypaper --restore

Waypaper hook not applying colors

# Check if hook is registered
grep post_command ~/.config/waypaper/config.ini

# Check hook logs
cat /tmp/waypaper-hook.log

Note

Everything is still in progress. Feel free to customize and adjust to your needs!