A comprehensive configuration repository for a modern Wayland-based Linux desktop environment using Hyprland as the window manager. This setup is optimized for productivity, gaming, and customization with pre-configured integration between multiple tools and utilities.

• Hyprland Window Manager – Tiling compositor for Wayland with advanced animations and GPU acceleration
• Gaming Mode – Performance profile toggle that disables animations, optimizes power settings, and pauses notifications for distraction-free gaming
• Custom Waybar Status Bar – Modular status bar with system tray, clock, media controls, and custom gamemode indicator
• Kitty Terminal – GPU-accelerated terminal with custom fonts and color themes
• Desktop Notifications – Dunst daemon configured to integrate seamlessly with Waybar aesthetic
• Systemd User Services – Automated daemon management for core session components
• Automatic Installation – install.sh script handles package installation, symlink management, and service enabling

This repository follows the GNU Stow symlink farm pattern. Each top-level directory represents a "package" containing a .config/ subdirectory structure that mirrors your home directory.

dotfiles/
├── hypr/                          # Hyprland window manager configuration
│   └── .config/hypr/
│       ├── hyprland.conf          # Core Hyprland settings (monitors, keybinds, rules)
│       ├── keybindings.conf       # All keyboard shortcuts and window management bindings
│       ├── monitors.conf          # Display configuration (resolution, refresh, scaling)
│       ├── workspaces.conf        # Workspace setup and behavior
│       ├── autostart.conf         # Applications to launch on session start
│       ├── hypridle.conf          # Idle management (screen off, suspend timeouts)
│       ├── hyprlock.conf          # Screen lock appearance and behavior
│       ├── windowrules.conf       # Per-app window rules and behaviors
│       ├── wallpapers/            # Wallpaper images for awww daemon
│       ├── bin/
│       │   └── wallpaper-manager  # Compiled wallpaper rotation daemon
│       └── scripts/
│           ├── gamemode.sh        # Gaming Mode toggle script
│           └── wallpaper_manager.go  # Wallpaper manager source (built at install)
│
├── systemd/                       # User-level systemd services
│   └── .config/systemd/user/
│       ├── hyprpolkitagent.service     # PolicyKit authentication service
│       ├── ssh-agent.service          # SSH key management daemon
│       ├── awww.service               # Wallpaper daemon
│       ├── waybar.service             # Status bar service
│       ├── hypridle.service           # Idle management service
│       ├── default.target.wants/      # Default session startup targets
│       └── graphical-session.target.wants/  # Graphical session targets
│
├── kitty/                         # Terminal emulator configuration
│   └── .config/kitty/
│       └── kitty.conf             # Terminal settings, fonts, colors, keybindings
│
├── waybar/                        # Status bar and system tray
│   └── .config/waybar/
│       ├── config.jsonc           # Module definitions and layout configuration
│       ├── style.css              # Colors, fonts, spacing, and visual styling
│       └── icons/                 # Custom icon definitions and theme
│
├── dunst/                         # Desktop notification daemon
│   └── .config/dunst/
│       └── dunstrc                # Notification styling, placement, and urgency levels
│
├── wlogout/                       # Lock/logout screen interface
│   └── .config/wlogout/
│       ├── layout                 # Button layout for power menu
│       ├── logout                 # Handler script for system commands
│       └── style.css              # Lock screen styling and theme
│
├── install.sh                     # Automated installation and setup script
└── README.md                      # This file

Each directory (e.g., hypr/, kitty/, waybar/) is a Stow "package." Running stow hypr creates symlinks from .config/hypr/ → ~/.config/hypr/. This modular approach makes it easy to:

• Enable/disable individual configurations
• Manage multiple profiles
• Keep dotfiles organized

• OS: Arch Linux or Arch-based distribution (Manjaro, EndeavourOS, etc.)
• Wayland Session: A Wayland login session (not X11)
• Standard Tools: git, curl, and bash

The easiest way to set up these dotfiles is to run the provided installation script:

# Clone the repository
git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Run the installer
bash install.sh

1. Installs yay (AUR helper) – If not already installed, builds and installs it from source
2. Installs all dependencies – Uses yay to install all required packages (see Dependencies section)
3. Builds Go executables – Compiles wallpaper_manager.go to bin/wallpaper-manager binary
4. Symlinks configurations – Uses stow to create symlinks for each package (hypr, kitty, waybar, etc.)
5. Enables systemd services – Reloads systemd daemon and enables/starts user services
6. Prints status – Shows progress and errors for each step

If you prefer granular control, use Stow manually:

# Clone the repository
git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Manually stow packages
stow hypr systemd kitty waybar dunst wlogout

# Install dependencies via your package manager
sudo pacman -S hyprland waybar kitty wlogout hyprlock hypridle dunst stow yay git base-devel

# Enable and start services
systemctl --user daemon-reload
systemctl --user enable --now waybar.service hypridle.service hyprpolkitagent.service awww.service ssh-agent.service

Edit install.sh before running it to customize which packages are installed:

# In install.sh, modify PACKAGES array:
PACKAGES=("hypr" "systemd" "kitty" "waybar" "dunst" "wlogout")

# And modify ALL_SOFTWARE array to add/remove packages:
ALL_SOFTWARE=(
    "hyprland"
    "waybar"
    "kitty"
    # ... add or remove as needed
)

Hyprland is a tiling compositor for Wayland with advanced animations, multiple workspace support, and GPU acceleration. The configuration is split into modular files for easier maintenance.

Core Files:

• hyprland.conf – Main configuration file that includes all other configs and sets core Hyprland behavior (decorations, animations, input settings, general options)

• keybindings.conf – All keyboard shortcuts organized by function:

  • Window management (focus, move, resize, fullscreen, float)
  • Workspace switching
  • Application launching
  • Gaming Mode toggle ($mainMod+Shift+G)
  • Media/brightness controls

• monitors.conf – Display configuration with monitor definitions:

  monitor=HDMI-1,1920x1080@60,0x0,1
  monitor=DP-1,3440x1440@100,1920x0,1
  

  Adjust resolution, refresh rate, position, and scaling for each display

• workspaces.conf – Workspace settings and per-workspace configurations

• autostart.conf – Applications/commands to execute on session start:

  • Daemons: waybar, awww, cliphist
  • Environment variables: Wayland/XDG settings
  • Wallpaper loading

• hypridle.conf – Idle management settings:

  • Screen timeout (e.g., turn off after 5 minutes)
  • Suspend behavior (e.g., suspend after 10 minutes)
  • Lock behavior (e.g., lock on idle)

• hyprlock.conf – Screen lock appearance:

  • Login widget styling
  • Password input appearance
  • Background/wallpaper display

• windowrules.conf – Application-specific window rules:

  • Window size/positioning
  • Floating vs tiling behavior
  • Opacity and animation rules

• wallpapers/ – Directory containing wallpaper images used by awww

• scripts/gamemode.sh – Gaming Mode toggle script that:

  • Disables animations, shadows, and blur
  • Sets system power profile to performance
  • Pauses desktop notifications via dunstctl
  • Can be toggled via keybinding or Waybar module

• scripts/wallpaper_manager.go – Automatic wallpaper rotation daemon that:

  • Rotates desktop wallpapers at configurable intervals (default: 1 hour)
  • Supports multiple monitors with independent wallpaper selection
  • Applies smooth transitions via awww
  • Pauses during Gaming Mode via lock file mechanism

Customization Tips:

• Update monitors.conf if your display setup differs
• Modify keybindings.conf to change keyboard shortcuts
• Add applications to autostart.conf for automatic launching
• Adjust idle timeouts in hypridle.conf for your preference
• Add window rules in windowrules.conf for app-specific behavior

Gaming Mode is a performance profile toggle that optimizes Hyprland for gaming:

What it does:

• Disables animations, shadows, blur, and window gaps in Hyprland (reduces latency and CPU usage)
• Sets system power profile to performance (unlocks higher CPU/GPU clocks)
• Pauses desktop notifications (prevents popups during gameplay)

How to use:

• Keybinding: Press $mainMod + Shift + G to toggle
• Waybar Module: Click the gaming mode icon in the status bar

How it works:

• Implemented in hypr/scripts/gamemode.sh
• Script checks Hyprland's animations:enabled option to detect current state
• On enable: runs hyprctl commands to disable effects + powerprofilesctl set performance + dunstctl set-paused true
• On disable: runs hyprctl reload to restore config + powerprofilesctl set balanced + dunstctl set-paused false

The Wallpaper Manager is an automated wallpaper switching daemon written in Go that rotates desktop backgrounds at configurable intervals. It supports multiple monitors with independent wallpaper selection and smooth transitions.

What it does:

• Automatic rotation: Changes wallpapers at a configurable interval (default: 1 hour / 3600 seconds)
• Multi-monitor support: Independently manages wallpapers for different displays (main monitor: DP-1, side monitor: DP-3)
• Random selection: Randomly picks wallpapers from designated folders (main and side directories)
• Smooth transitions: Uses awww daemon to apply transitions with configurable FPS and animation steps
• Gaming Mode integration: Automatically pauses wallpaper switching during Gaming Mode via lock file mechanism
• Lazy loading: Scans wallpaper directories once on startup, no continuous disk I/O

Features:

Setup and Configuration:

The Wallpaper Manager runs as a systemd user service and is configured through the awww.service file:

[Unit]
Description=awww Wallpaper Daemon
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/path/to/wallpaper_manager -interval 3600
Restart=on-failure
RestartSec=5

Wallpaper Directory Structure:

~/.config/hypr/wallpapers/
├── main/          # Main monitor wallpapers (DP-1)
│   ├── wallpaper1.jpg
│   ├── wallpaper2.png
│   └── ...
└── side/          # Side monitor wallpapers (DP-3)
    ├── landscape1.jpg
    ├── landscape2.webp
    └── ...

Customization:

1. Change rotation interval:

   # Edit systemd service to change interval (in seconds)
   # 3600 = 1 hour, 1800 = 30 minutes, etc.
   systemctl --user edit awww.service

2. Add wallpaper images:

   • Place .jpg, .png, .webp, or .jpeg files in ~/.config/hypr/wallpapers/main/ and/or ~/.config/hypr/wallpapers/side/
   • Manager will automatically discover and include them

3. Configure monitor outputs:

   • Edit hypr/scripts/wallpaper_manager.go (lines 43-44) to match your display names:

   cmdMain := exec.Command("awww", "img", "-o", "DP-1", ...)  // Your main monitor
   cmdSide := exec.Command("awww", "img", "-o", "DP-3", ...)  // Your side monitor

4. Adjust transition smoothness:

   • Modify --transition-fps (currently 60 FPS) and --transition-step (currently 90) in the source code for different transition effects

Gaming Mode Integration:

When Gaming Mode is enabled via $mainMod + Shift + G:

• A lock file /tmp/wallpaper_cycle.lock is created
• The Wallpaper Manager detects this and pauses switching
• When Gaming Mode is disabled, the lock file is removed and switching resumes

Manual Execution:

Build and run the Wallpaper Manager manually:

# Navigate to scripts directory
cd ~/.config/hypr/scripts

# Compile the Go program
go build -o wallpaper_manager wallpaper_manager.go

# Run with default 1-hour interval
./wallpaper_manager

# Run with custom interval (e.g., 30 minutes = 1800 seconds)
./wallpaper_manager -interval 1800

# Kill the process when done
killall wallpaper_manager

Troubleshooting:

• Wallpapers not changing: Verify awww-daemon is running (pgrep awww)
• Gaming Mode not pausing: Confirm lock file mechanism is working or manually restart the daemon
• No images found: Ensure wallpaper directories exist and contain valid image files
• Slow transitions: Reduce -interval value or adjust FPS/step values in source code

Kitty is a modern, GPU-accelerated terminal emulator with excellent performance and feature support.

Configuration:

• kitty.conf – Master configuration file including:
  • Font family and size (default: JetBrains Mono Nerd Font)
  • Color scheme and theme
  • Keyboard shortcuts for terminal operations
  • Scrollback history settings
  • Mouse and copy-paste behavior
  • Shell integration
  • Padding and line height

Customization Tips:

• Change font: font_family and font_size options
• Modify colors: Update color palette definitions
• Define custom keybindings for terminal-specific operations
• Adjust scrollback to control history depth

Waybar is a highly customizable status bar for Wayland. It displays system information, has integrated system tray, and supports custom modules.

Configuration:

• config.jsonc – Defines modules, layout, and behavior:

  • Modules list and order
  • Module-specific settings (pulse, network, battery, etc.)
  • Bar position and margins
  • Systemd service integration
  • Gaming Mode custom module
  • Shortcuts and click commands
  • Signal handlers for real-time updates

• style.css – Visual styling:

  • Colors and themes (matches Hyprland aesthetic)
  • Font and text styling
  • Module spacing and sizing
  • Hover and active states
  • Progress bar styling
  • Gaming Mode indicator styling

• icons/ – Custom icon definitions and theme overrides

Available Modules:

• clock – Date and time display
• network – WiFi status and connectivity
• battery – Battery percentage and status
• pulseaudio – Volume control
• backlight – Screen brightness
• cpu – CPU usage percentage
• memory – RAM usage
• disk – Disk space usage
• custom/gamemode – Gaming Mode indicator (custom module)
• tray – System tray integration
• And many more...

Customization Tips:

• Add/remove modules by editing config.jsonc
• Modify bar position (top/bottom) and margins
• Customize colors and fonts in style.css
• Create custom modules for specific tasks
• Adjust update intervals for performance

Dunst is a lightweight notification daemon that displays desktop notifications. It integrates with Hyprland and is paused during Gaming Mode.

Configuration:

• dunstrc – Main configuration file:
  • Monitor selection where notifications appear
  • Origin and offset (where notifications spawn on screen)
  • Width, height, and dynamic sizing
  • Notification limits
  • Corner radius and frame styling
  • Font selection (matches Waybar aesthetic)
  • Padding and spacing
  • Progress bars for volume/brightness feedback
  • Urgency levels (low, normal, critical) with different styling/timeouts

Urgency Levels:

• low – 5 second timeout, muted colors
• normal – 10 second timeout, standard visibility
• critical – No timeout, highlighted with red frame

Gaming Mode Integration:

During Gaming Mode, the gamemode.sh script pauses notifications:

dunstctl set-paused true   # Pause on enable
dunstctl set-paused false  # Resume on disable

Customization Tips:

• Adjust timeout values for notification duration
• Change colors to match your theme
• Modify offset to reposition notifications
• Adjust width and height for different screen sizes
• Enable/disable progress_bar for volume/brightness feedback

Wlogout provides an on-screen lock/logout/power menu interface for Hyprland sessions.

Configuration:

• layout – Button layout definition:

  • Specifies which buttons appear and their order
  • Button labels and icons
  • Button actions (power off, reboot, logout, lock, etc.)

• logout – Handler script:

  • Executes system commands based on button clicks
  • Uses systemctl for power operations
  • Handles logout and lock actions

• style.css – Visual styling:

  • Background and overall layout styling
  • Button appearance, hover, and active states
  • Theming and colors

Customization Tips:

• Edit layout to add/remove buttons or change their order
• Modify logout script to customize system commands
• Adjust style.css for color and appearance changes

User-level systemd services that manage daemons and utilities for the graphical session.

Service Files:

• hyprpolkitagent.service – PolicyKit authentication agent

  • Handles password prompts for privileged operations
  • Launched on graphical session start

• ssh-agent.service – SSH key management

  • Manages SSH keys for authentication
  • Provides SSH_AUTH_SOCK environment variable

• awww.service – Wallpaper daemon

  • Manages desktop wallpapers
  • Supports animated wallpapers via awww

• waybar.service – Status bar service

  • Runs the Waybar process
  • Respawn on crash

• hypridle.service – Idle management

  • Monitors user activity
  • Triggers idle actions (screen off, suspend, lock)

Service Targets:

• default.target.wants/ – Services linked here start with the default user target
• graphical-session.target.wants/ – Services linked here start with the graphical session

Customization Tips:

• Edit service files to add dependencies or environment variables
• Create new service files for custom daemons
• Adjust Type and Restart policies for different behavior
• Use Environment and ExecStart to customize commands

• Distribution: Arch Linux, Manjaro, EndeavourOS, or other Arch-based distribution
• Display Server: Wayland (not X11)
• Build Tools: base-devel package (required for building AUR packages with yay)
• Package Manager: pacman (with AUR support via yay)
• Symlink Manager: stow (for managing dotfiles)

All dependencies are automatically installed by install.sh.

After installation, your Hyprland session should start automatically on the next login. Default keybindings include:

• $mainMod + Return – Open terminal (Kitty)
• $mainMod + Q – Close focused window
• $mainMod + V – Toggle floating window
• $mainMod + F – Toggle fullscreen
• $mainMod + 1-9 – Switch to workspace 1-9
• $mainMod + Shift + 1-9 – Move window to workspace 1-9
• $mainMod + Shift + G – Toggle Gaming Mode
• $mainMod + E – Open file manager
• $mainMod + Esc – Open logout menu (wlogout)

See keybindings.conf for the complete list.

Edit hypr/monitors.conf with your display configuration:

# Format: monitor=NAME,RESOLUTION@REFRESH,POSITION,SCALE
monitor=DP-1,3440x1440@100,0x0,1
monitor=HDMI-1,1920x1080@60,3440x0,1.25
monitor=eDP-1,disable  # Disable built-in laptop display

Run hyprctl monitors to list connected displays and their names.

Edit hypr/keybindings.conf to add/modify shortcuts:

# Syntax: bind = MODIFIERS, KEY, DISPATCHER, ARGUMENTS
bind = $mainMod, Q, killactive
bind = $mainMod SHIFT, Q, exec, systemctl poweroff

Edit hypr/autostart.conf to add applications that launch on session start:

# Syntax: exec-once = command
exec-once = $terminal  # Start terminal
exec-once = firefox &  # Start Firefox in background

Edit hypr/hypridle.conf to adjust screen timeout and suspend behavior:

listener {
    timeout = 300    # 5 minutes
    on-timeout = hyprctl dispatch dpms off
    on-resume = hyprctl dispatch dpms on
}

Edit waybar/config.jsonc to add more modules to the status bar:

"modules-center": [
    "clock",
    "custom/weather",  // Add custom weather module
    "custom/gamemode"
]

Edit waybar/style.css to change colors, fonts, and layout:

* {
    font-family: "JetBrains Mono";
    font-size: 12px;
    color: #cdd6f4;
    background: #1e1e2e;
}

1. Ensure you're using a Wayland session (not X11)
2. Check if required packages are installed: pacman -Q hyprland waybar
3. View Hyprland logs: journalctl --user -u Hyprland -n 50

1. Verify symlinks are correct: ls -la ~/.config/waybar/
2. Check service status: systemctl --user status waybar
3. Restart the service: systemctl --user restart waybar

1. Verify symlinks were created: ls -la ~/.config/hypr/
2. Re-run stow with force: cd ~/dotfiles && stow -R hypr waybar kitty systemd wlogout dunst
3. Reload Hyprland: $mainMod + Esc then open a new session

1. Ensure powerprofilesctl is installed: pacman -Q power-profiles-daemon
2. Check if Gaming Mode script is executable: ls -la ~/.config/hypr/scripts/gamemode.sh
3. Test manually: ~/.config/hypr/scripts/gamemode.sh 1

1. Ensure dunst is running: pgrep dunst
2. Start dunst manually: dunst &
3. Add to autostart: Edit hypr/autostart.conf and add exec-once = dunst

1. Install required fonts: sudo pacman -S ttf-jetbrains-mono-nerd noto-fonts-emoji
2. Reload terminal: Close and reopen Kitty
3. Check font settings in kitty/kitty.conf

Contributions are welcome! To contribute:

1. Test thoroughly – Ensure changes work on a fresh Wayland/Hyprland session
2. Update documentation – Modify the README if adding new files or features
3. Verify symlinks – Run stow to ensure configurations link correctly
4. Check services – Confirm systemd services start without errors
5. Commit clearly – Use clear, descriptive commit messages

# Create a feature branch
git checkout -b feature/my-improvement

# Make your changes and commit
git add .
git commit -m "Add feature: brief description"

# Push and open a pull request
git push origin feature/my-improvement

MIT License – Feel free to reuse, modify, and adapt these dotfiles for your setup. See the LICENSE file for full details (if included).

• Hyprland Wiki – Comprehensive Hyprland documentation
• Waybar GitHub – Waybar source and module documentation
• Kitty Documentation – Kitty terminal documentation
• Dunst GitHub – Dunst notification daemon
• GNU Stow Manual – Symlink farm management
• systemd User Services – User service guide
• Wayland Protocol – Wayland display server protocol

Happy tiling! 🚀