~/.dotfiles

Personal Arch Linux dotfiles setup using GNU stow for managing configuration files. All configs are symlinked from this repo into ~/.config/, making this the single source of truth.

This setup is optimized for a single-monitor desktop. Multi-monitor behavior (for example launcher screen targeting) is supported but not the primary focus.

What's Included

Window Manager & Desktop

• Hyprland - Wayland window manager (Lua config) with custom scripts for auth, power, media, wallpaper, and screen capture
• QuickShell - Status bar, notification center, app launcher, and script menus (QML)
• Shmooz - Screen magnifier (zoom, annotation, spotlight, color picker)

Shell & Terminal

• Fish - Shell configuration and functions
• Ghostty - Terminal emulator config
• Tmux - Terminal multiplexer with plugins:
  • tpm - Plugin manager
  • tmux-resurrect - Session persistence
  • tmux-gruvbox - Color theme

Editor & Tools

• Neovim - Editor configuration
• Systemd - User service units (wallpaper rotation, battery notifications)

Screen Recording

• Screen Capture - Video recording with wf-recorder (region select, audio source picker, clipboard integration, desktop notifications). See .config/hypr/scripts/screen_capture.md.

Installation

Prerequisites

• Arch Linux with pacman
• git (required for cloning)
• Sudo access

Quick Start

Make a backup snapshot first:

sudo pacman -S timeshift
sudo timeshift --create --comments "Before installing .dotfiles"

Clone and install:

git clone --recurse-submodules https://codeberg.org/galtrhan/dotfiles ~/.dotfiles
cd ~/.dotfiles
chmod +x install.sh
./install.sh

The script will:

1. Update pacman database
2. Install all required packages
3. Remove any existing default configs
4. Initialize/update git submodules (tmux plugins)
5. Install udev LED permission rules for mute/mic mute keys
6. Apply stow to create symlinks
7. Disable dunst if it was previously enabled (QuickShell owns notifications)
8. Start bluetooth service

Manual Installation

If you prefer to install packages separately:

git clone --recurse-submodules https://codeberg.org/galtrhan/dotfiles ~/.dotfiles
cd ~/.dotfiles
git submodule update --init --recursive
sed "s/__DOTFILES_USER__/$(id -un)/g; s/__DOTFILES_GROUP__/$(id -gn)/g" \
 ~/.dotfiles/.config/hypr/udev/90-audio-leds.rules \
 | sudo tee /etc/udev/rules.d/90-audio-leds.rules > /dev/null
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=leds
stow . # Create symlinks for all configs

Init System Setup

Services are provided for both systemd (Arch) and runit (Artix):

On Arch (systemd)

After stowing, enable the wallpaper rotation service:

systemctl --user enable wallpaper-rotate.service
systemctl --user start wallpaper-rotate.service
systemctl --user enable --now battery-notify.timer

On Artix (runit)

After stowing, symlink the runit service:

mkdir -p ~/.local/share/runit/sv
ln -s ~/.config/runit/sv/wallpaper-rotate ~/.local/share/runit/sv/

Then ensure runsvdir monitors your service directory. If not already running, add to your shell startup (e.g., ~/.config/fish/config.fish):

runsvdir -P ~/.local/share/runit/sv

Managing Configs with Stow

# Apply all configs
git submodule update --init --recursive # Ensure tmux plugins are present
stow .
# Apply specific configs only
stow fish nvim tmux quickshell
# Preview changes without applying
stow -nv .
# Remove symlinks
stow -D .
# Reapply symlinks
stow -R .

Keybinds

General

Screen Capture & Recording

Screen Magnifier

Window Management

Wallpaper & Multimedia

Hyprland Scripts

Scripts live in .config/hypr/scripts/. Hyprland is configured via .config/hypr/hyprland.lua.

Authentication

Sudo askpass behavior:

• Sends a critical desktop notification when a password is required
• Shows a QuickShell password overlay via qs ipc call menu show_password
• Returns the entered password on stdout for sudo -A (empty string if cancelled)

Fish is configured in .config/fish/config.fish to use sudo -A only when stdin is not a terminal (e.g. agent subprocesses). Interactive terminal sudo prompts in the shell as usual.

Requires QuickShell to be running (started with Hyprland).

Power & Session

Hardware Controls

Window Layout

Wallpaper

Full wallpaper system docs: .config/hypr/scripts/wallpaper.md

Screen Capture & Screenshots

Full screen capture docs: .config/hypr/scripts/screen_capture.md

QuickShell Launcher & Menus

App launcher and script menus are built into QuickShell (.config/quickshell/launcher/). Hyprland keybinds call qs ipc:

Examples:

qs ipc call launcher toggle
qs ipc call -- menu show "Power Menu" $'Lock\nLogout\nSuspend'
~/.config/hypr/scripts/qs-menu.sh "Recording Audio" "None (no audio)" "System Audio (output)"

QuickShell auto-reloads QML on save. Restart with Super+Shift+O or pkill quickshell; quickshell &.

Battery Meltdown Overlay

At 5% battery while discharging, QuickShell shows a full-screen critical overlay (not the corner popup): flashing red UI, looping meltdown.mp3 alarm, and a 60-second countdown after which the system suspends. Click to dismiss or plug in to cancel.

Requires battery-notify.timer, ffmpeg (ffplay), and ~/.config/quickshell/sounds/meltdown.mp3. Full details: .config/hypr/scripts/battery.md.

Configuration

Common tuning points:

Notification history exclusions (volume/brightness/keyboard OSD) are in the same NotificationService.qml file under historyExcludedApps.

Directory Structure

~/.dotfiles/
├── .config/
│ ├── fish/ # Shell configuration
│ ├── hypr/ # Hyprland Lua config, window rules, and scripts (see Hyprland Scripts)
│ ├── quickshell/ # Status bar, notifications, app launcher, menus (QML)
│ ├── nvim/ # Neovim configuration
│ ├── tmux/ # Tmux + plugins
│ ├── ghostty/ # Terminal emulator config
│ └── systemd/ # Systemd user units
├── install.sh # Installation script (packages + stow)
└── README.md

Notes

• Optimized for a single monitor; multi-monitor setups may need launcher/notification tweaks
• This setup is tailored for Wayland (Hyprland) and may require adjustments for other environments
• Config submodules are included for tmux plugins—clone with --recurse-submodules
• Each config directory may have its own documentation
• Brightness control (brightnessctl) is required for screen brightness adjustments. Installed by install.sh
• Mute LED control for XF86AudioMute and XF86AudioMicMute uses udev ownership rules installed by install.sh
• Sudo askpass requires Fish (for the non-TTY sudo -A wrapper), QuickShell running for the password overlay, and applies when stdin is not a terminal
• Desktop notifications are handled by QuickShell (notify-send / libnotify). Disable or mask dunst.service if migrating from an older setup
• Battery meltdown at 5% uses a QuickShell full-screen overlay with alarm sound and auto-suspend countdown — see .config/hypr/scripts/battery.md
• For development or contributions, see AGENTS.md