A safety-first agent skill that installs, configures, verifies, repairs, and removes Hyprland on Fedora Linux while preserving existing desktop packages and user backups.

🎯 Why This Project Exists

Setting up Hyprland on Fedora can be tedious. You have to configure Wayland portals, sort out PipeWire audio, select launcher/terminal defaults, and configure GPU flags—especially if you're running NVIDIA or hybrid graphics.

After installing this skill through your agent's supported skill mechanism, ask:

"Install Hyprland on my Fedora system."

The agent inspects your system hardware, creates timestamped backups of existing settings, proposes Fedora package changes, and can create a minimal Hyprland configuration after you approve mutating steps. It detects GPU vendors but does not install or configure graphics drivers.

✨ Key Features

🛡️ Safety First & Mandatory Backups: Never overwrites your existing ~/.config/hypr/ without creating a timestamped backup in ~/.local/state/fedora-hyprland-installer/backups/.
🐧 Fedora-Native: Built specifically for Fedora. Uses dnf, systemctl, and standard Fedora package repositories.
⚡ GPU Aware: Detects NVIDIA, AMD Radeon, Intel, and hybrid setups and adds a conservative Hyprland-native cursor workaround for detected NVIDIA hardware.
🤝 Desktop Coexistence: Never removes GNOME, KDE, or Xfce. Hyprland is added as a session option at your GDM/SDDM login screen.
🛠️ Scoped Repair: Reports a missing config or portal package and inactive PipeWire/WirePlumber services; approved fixes can be applied with repair.sh --apply.
🧼 Scoped Removal: Removes the listed Hyprland-specific packages while preserving your base desktop and backups.

📦 What Gets Installed

When installing, the skill provisions a minimal, fast, and modern desktop stack:

Component	Package / Tool	Purpose
Compositor	`hyprland`	Dynamic tiling Wayland compositor
Terminal	`kitty`	Fast, GPU-accelerated terminal
Launcher	`wofi`	Application launcher menu
Status Bar	`waybar`	Desktop panel & bar
Portals	`xdg-desktop-portal-hyprland`, `xdg-desktop-portal-gtk`	Screen sharing & file dialogs
Audio	`pipewire`, `wireplumber`	Low-latency audio & stream routing
Notifications	`dunst`	Desktop notification daemon
Screenshots	`grim`, `slurp`, `wl-clipboard`	Screen capture & clipboard support

🚀 Quick Start & Usage

Agent usage

Use the installation method documented by your agent or by the repository catalog, then invoke the skill in natural language. The skill does not assume a particular global directory or CLI executable.

Fresh Install: "Install Hyprland on my Fedora machine."
Health Check: "Verify my Hyprland installation."
Troubleshoot & Fix: "Fix my screen sharing on Hyprland" or "Hyprland won't start."
Update Setup: "Update my Hyprland packages."
Uninstall: "Uninstall Hyprland."

🛠️ Direct Terminal Utilities

You can also run the built-in utilities in scripts/ directly:

# Detect hardware, OS, and session information
bash ./scripts/detect-system.sh

# Detect GPU hardware (NVIDIA / AMD / Intel)
bash ./scripts/detect-gpu.sh

# Run preflight system verification
bash ./scripts/preflight.sh

# Verify health of your current Hyprland installation
bash ./scripts/verify.sh

# Run the isolated non-destructive test suite
bash ./tests/test-scripts.sh

📁 Repository Structure

fedora-hyprland-installer/
├── SKILL.md                 # Antigravity Agent Skill definition & workflow rules
├── README.md                # Project documentation
├── LICENSE                  # MIT License
├── scripts/                 # Modular, safe shell scripts
│   ├── detect-system.sh
│   ├── detect-gpu.sh
│   ├── preflight.sh
│   ├── install.sh
│   ├── configure.sh
│   ├── verify.sh
│   ├── backup.sh
│   ├── repair.sh
│   └── uninstall.sh
├── references/              # Detailed knowledge base for Fedora, GPUs & Wayland
│   ├── fedora.md
│   ├── hyprland.md
│   ├── nvidia.md
│   ├── amd.md
│   ├── intel.md
│   ├── wayland.md
│   ├── portals.md
│   └── troubleshooting.md
└── tests/                   # Safe, non-destructive test suite
    ├── test-detection.sh
    └── test-scripts.sh

🤝 Contributing

Contributions, bug reports, and improvements are welcome! Feel free to open an issue or submit a pull request on GitHub.

📜 License

Distributed under the MIT License included in LICENSE.