Hyprland Dotfiles

A clean starting point for a modern Hyprland desktop using the current Lua configuration format, Quickshell, Ghostty, Zsh, Catppuccin Mocha, a GTK/libadwaita application stack, and optional Steam Gaming Mode integration.

Warning

This is an AI-assisted ("vibe coded") personal dotfiles project. Review the scripts and configuration before using them. Use at your own risk.

Status

This repository is an early scaffold. Review monitor, launcher, wallpaper, autostart, and Gaming Mode settings before using it as your daily desktop.

Structure

config/hypr/                    Hyprland, Hyprlock, Hypridle, Hyprpaper
config/hypr/modules/            Modular Lua configuration
config/quickshell/sean-shell/   Quickshell panel, searchable app launcher, and future widgets
config/ghostty/                 Ghostty terminal configuration
config/zsh/                     Zsh interactive shell configuration
docs/                           Setup notes, including Steam Gaming Mode
packages/                       Arch repository and optional AUR lists
scripts/                        Bash installer, uninstaller, health check, and Gaming Mode launcher
wallpapers/                     User-provided wallpapers
screenshots/                    Repository screenshots

Install

On an Arch-based system, download the repository and run its installer with:

curl -fsSL https://raw.githubusercontent.com/seandmoore/hyprland-dotfiles/main/install.sh | bash

The bootstrap installs Git when needed, clones the repository to ~/.local/share/hyprland-dotfiles, and runs scripts/install.sh. Running it again safely fast-forwards a clean checkout before reinstalling. It stops if the checkout has local changes or an unexpected Git remote.

To review the downloaded bootstrap before running it:

curl -fsSL https://raw.githubusercontent.com/seandmoore/hyprland-dotfiles/main/install.sh -o /tmp/hyprland-dotfiles-install.sh
less /tmp/hyprland-dotfiles-install.sh
bash /tmp/hyprland-dotfiles-install.sh

You can still install from a manual clone:

git clone https://github.com/seandmoore/hyprland-dotfiles.git
cd hyprland-dotfiles
chmod +x scripts/*.sh
./scripts/install.sh

The installer targets Arch-based systems, validates package and XDG paths, installs required packages, keeps backups private to your user, and creates symlinks from the repository into your home directory. The uninstaller removes only symlinks that still point back to this repository and preserves unrelated replacements.

Quickshell is the intended interface for the launcher, panels, overlays, and related desktop widgets, so no separate application launcher is installed. Press Super+Space to toggle the searchable application launcher. The keybind calls the running sean-shell instance over Quickshell IPC, and launching an entry uses its parsed desktop-file command.

Zsh is installed and configured as the preferred interactive shell. The installer deliberately does not change your login shell automatically. To make Zsh your default after installation, run:

chsh -s /usr/bin/zsh

Log out and back in for the login-shell change to take effect.

Project automation remains written in Bash for portability and compatibility with Codex, CI environments, and other Arch-based systems.

Steam Gaming Mode

The installer adds hypr-gaming-mode to ~/.local/bin and binds Super+G to automatic mode.

hypr-gaming-mode auto
hypr-gaming-mode nested
hypr-gaming-mode session

auto uses a dedicated session when a supported steamos-session-select helper is available and otherwise launches Steam Gamepad UI inside fullscreen Gamescope. The script intentionally avoids forcefully terminating Hyprland when no safe session switcher is present.

See docs/gaming-mode.md for dedicated-session setup, display selection, and limitations.

GTK-focused desktop apps

The default package list favors GTK/libadwaita applications, including Nautilus, Mission Center, Loupe, Papers, and GNOME Text Editor. This keeps the Hyprland desktop visually consistent without requiring the full GNOME desktop environment.

Validate

./scripts/health-check.sh
hyprctl reload

Important customization

1. Run hyprctl monitors and replace the generic monitor rule.
2. Add a wallpaper to wallpapers/ and update config/hypr/hyprpaper.conf.
3. Review config/hypr/modules/autostart.lua.
4. Expand the Quickshell shell one component at a time.
5. Test Gaming Mode in nested mode before configuring a dedicated session.

Safety

This repository is developed with significant assistance from OpenAI Codex/ChatGPT using an AI-assisted ("vibe coding") workflow. It may contain mistakes, incomplete configuration, or assumptions that do not fit every system.

Review every script and configuration file before running the installer, especially on a production machine. You are responsible for any changes made to your system.

The installer does not change your login shell, configure a display manager, or delete backups. Do not run it as root.

Acknowledgments

Created and maintained by Sean Moore, with development and documentation assistance from OpenAI Codex (ChatGPT).

Codex-assisted commits use GitHub's linked Codex co-author identity so the contribution history remains transparent.

License

GPL-3.0-only. See LICENSE.