Niri + Quickshell Dotfiles

A modern, Windows-like desktop experience for Fedora Linux using the Niri tiling window manager and Quickshell taskbar.

---

Table of Contents

• Overview
• Features
• Quick Start
• Installation
• Directory Structure
• Keybindings
• Customization
• Troubleshooting
• Documentation
• Contributing
• License

---

Overview

This dotfiles collection provides a complete desktop environment setup for Fedora Linux, combining:

• Niri - A scrollable tiling window manager that automatically arranges windows in columns
• Quickshell - A QtQuick-based shell for creating a polished, Windows-style taskbar
• KDE Applications - Dolphin, Konsole, and Kate for a cohesive desktop experience
• Supporting tools - Dunst (notifications), Bemenu (launcher), Hyprlock (screen lock), and more

The result is a productive tiling WM setup with the familiarity of a Windows-style interface.

---

Features

Feature	Description
Windows-like Taskbar	Bottom panel with Start menu, task list, system tray, and clock
Start Menu	Application launcher with search and pinned apps (Dolphin, Konsole, Kate, Firefox)
Dark Theme	Windows 11-inspired color scheme with smooth animations
Tiling WM	Automatic window management with Niri's column-based layout
Notifications	Dunst daemon with styled popups
Screenshots	Utility script with area selection and editing
Screen Lock	Hyprlock with blurred background and time display
Intuitive Keys	Vim-style navigation + Windows-like shortcuts
Easy Setup	One-command installation script for Fedora

---

Quick Start

Prerequisites

• Fedora Linux 38+ (or other Wayland-compatible distribution)
• Git for cloning the repository
• Internet connection for downloading dependencies

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/naravisuals-agentic-dotfiles.git
cd naravisuals-agentic-dotfiles

# 2. Run the interactive installer
./scripts/install.sh

# 3. Logout and select "Niri" at the login screen

The installer provides:

• Interactive prompts for installation type
• Automatic backup of existing configurations
• Progress indicators and colored output
• Detailed logging to /tmp/dotfiles-install-*.log
• Post-installation summary with next steps

Installation Options

# Full installation (default)
./scripts/install.sh

# Minimal installation (core dependencies only)
./scripts/install.sh --minimal

# Configuration only (skip package installation)
./scripts/install.sh --config

Post-Installation

After logging into Niri:

1. Test the taskbar - Quickshell should start automatically
2. Open a terminal - Press Super + Return
3. Launch apps - Press Super + D for the application menu
4. Reload config - Press Super + R to reload Quickshell

---

Directory Structure

naravisuals-agentic-dotfiles/
|
├── niri/
│   └── config.kdl              # Niri window manager configuration
│
├── quickshell/
│   ├── shell.qml               # Entry point (loaded by quickshell)
│   ├── main.qml                # ShellRoot with global config
│   ├── BarContainer.qml        # Main taskbar layout
│   ├── StartSection.qml        # Start button & pinned apps
│   ├── TaskList.qml            # Open windows task list
│   ├── SystemTraySection.qml   # System tray, volume, clock
│   ├── qmldir                  # Module definition
│   └── README.md               # Quickshell configuration guide
│
├── dunst/
│   └── dunstrc                 # Notification daemon settings
│
├── bemenu/
│   └── config                  # Application launcher theme
│
├── wlogout/
│   └── style.css               # Power menu styling
│
├── hypr/
│   └── hyprlock.conf           # Screen lock configuration
│
├── bin/
│   ├── launch.sh               # Enhanced app launcher (bemenu-based)
│   └── screenshot.sh           # Screenshot utility script
│
├── scripts/
│   ├── install.sh              # Interactive installer
│   ├── uninstall.sh            # Uninstaller script
│   ├── run-module.sh           # Run individual installation modules
│   ├── symlink.sh              # Symlink management utility
│   ├── modules/                # Installation modules
│   └── utils/                  # General-purpose utility scripts
│
├── gtk/
│   └── settings.ini            # GTK theme configuration
│
├── neovim/
│   ├── README.md               # LazyVim documentation
│   ├── .lazyvim.json           # LazyVim configuration
│   └── lua/plugins/            # LazyVim plugin configs
│
├── docs/
│   ├── INSTALLATION.md         # Detailed installation guide
│   ├── CONFIGURATION.md        # Configuration reference
│   ├── KEYBINDINGS.md          # Complete keybindings list
│   ├── TROUBLESHOOTING.md      # Troubleshooting guide
│   └── UTILITIES.md            # Utility scripts documentation
│
├── LICENSE                     # MIT License
└── README.md                   # This file

---

Keybindings

Essential Shortcuts

Keys	Action
Super + Return	Open terminal (Konsole)
Super + D	Open application launcher
Super + Q	Close focused window
Super + Space	Toggle floating mode
Super + F	Toggle fullscreen
Super + R	Reload Quickshell

Window Navigation (Vim-style)

Keys	Action
Super + H	Focus left column
Super + L	Focus right column
Super + K	Focus window up
Super + J	Focus window down

Window Management

Keys	Action
Super + Shift + H	Move column left
Super + Shift + L	Move column right
Super + Shift + K	Move column up
Super + Shift + J	Move column down
Super + C	Center window

Workspaces

Keys	Action
Super + 1-9	Switch to workspace 1-9
Super + 0	Switch to workspace 10
Super + Tab	Next workspace
Super + Shift + Tab	Previous workspace
Super + Shift + 1-9	Move window to workspace

System Controls

Keys	Action
Super + B	Bluetooth manager
Super + M	Volume control (pavucontrol)
Super + L	Lock screen
Super + X	Power menu
Super + E	File manager (Dolphin)
Super + W	Web browser (Firefox)

Screenshots

Keys	Action
Super + Print	Full screen screenshot
Super + Alt + Print	Area screenshot

For a complete list of keybindings, see docs/KEYBINDINGS.md.

---

Customization

Niri Configuration

Edit ~/.config/niri/config.kdl:

// Adjust gaps between windows
layout {
    gaps 8
    outer-gaps 8
}

// Change focus ring color
focus-ring {
    width 2
    color "#4a9eff"
}

// Add custom keybindings
binds {
    Mod {
        T spawn "thunderbird"
    }
}

Quickshell Taskbar

Edit files in ~/.config/quickshell/:

// bar.qml - Change bar height and position
readonly property int barHeight: 48
anchor: ShellSurface.Anchor.Bottom

// StartSection.qml - Modify pinned apps
property var apps: [
    {name: "Firefox", icon: "firefox", command: "firefox"},
    {name: "Your App", icon: "your-icon", command: "your-app"},
]

// SystemTraySection.qml - Change clock format
text: Qt.formatTime(now, "h:mm AP")  // 12-hour
text: Qt.formatTime(now, "HH:mm")    // 24-hour

Color Scheme

The default Windows 11-inspired theme:

// In quickshell/bar.qml
readonly property color bgColor:     "#202020"
readonly property color bgHover:     "#3a3a3a"
readonly property color bgActive:    "#4a4a4a"
readonly property color accentColor: "#4a9eff"
readonly property color textColor:   "#ffffff"
readonly property color textMuted:   "#aaaaaa"

For detailed customization options, see docs/CONFIGURATION.md.

---

Troubleshooting

Common Issues

Niri Won't Start

# Check if running Wayland
echo $XDG_SESSION_TYPE

# Try software rendering
WLR_RENDERER=pixman niri

# Check GPU drivers
dmesg | grep -i drm

Quickshell Not Visible

# Check if running
pgrep quickshell

# View logs
journalctl --user -u quickshell

# Manual reload
quickshell reload

No Notifications Appearing

# Ensure dunst is running
pgrep dunst

# Start manually if needed
dunst &

Icons Not Showing

# Install icon theme
sudo dnf install breeze-icon-theme papirus-icon-theme

# Refresh icon cache
gtk-update-icon-cache

For complete troubleshooting guide, see docs/TROUBLESHOOTING.md.

---

Documentation

Additional documentation is available in the docs/ directory:

Document	Description
INSTALLATION.md	Detailed installation instructions
CONFIGURATION.md	Configuration reference for all components
KEYBINDINGS.md	Complete keybindings reference
TROUBLESHOOTING.md	Comprehensive troubleshooting guide
UTILITIES.md	Utility scripts documentation

---

Contributing

Contributions are welcome. Here is how you can help:

Ways to Contribute

1. Report bugs - Open an issue with detailed steps to reproduce
2. Suggest features - Share ideas for improvements
3. Submit PRs - Fix bugs or add new features
4. Improve docs - Clarify instructions or add examples
5. Share screenshots - Help build the screenshots section

Development Workflow

# Fork the repository
git clone https://github.com/yourusername/naravisuals-agentic-dotfiles.git
cd naravisuals-agentic-dotfiles

# Create a feature branch
git checkout -b feature/your-feature-name

# Make changes and test
# ...

# Commit with clear messages
git commit -m "feat: add new feature description"

# Push and create PR
git push origin feature/your-feature-name

Code Style

• Use consistent indentation (4 spaces for KDL, 4 spaces for QML)
• Add comments for complex configurations
• Test changes before submitting

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 naravisuals-agentic-dotfiles

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

Acknowledgments

• Niri - The innovative scrollable tiling window manager
• Quickshell - Beautiful Wayland shell components
• Dunst - Lightweight notification daemon
• Hyprlock - Modern screen locker
• Bemenu - Dynamic menu library