Dotfiles

Personal dotfiles for Arch Linux, Fedora, and Debian/Ubuntu with optional Hyprland or Niri desktop support.

Features

• Multi-distro support: Works on Arch Linux, Fedora, and Debian/Ubuntu (extensible to other distros)
• KDE base assumed: Desktop installs expect a KDE Plasma base (e.g. Fedora KDE Spin, Kubuntu). Polkit, file manager, and theming packages rely on KDE components already being present.
• Desktop or terminal mode: Choose a full desktop setup or a lightweight terminal-only install
• Interactive installer: Beautiful TUI prompts using gum
• Modular packages: Choose what to install (Hyprland, Niri, Development, Gaming, AI, etc.)
• Desktop AppImage support: Installs FUSE runtime for AppImage on desktop setups (Arch: fuse2, Fedora: fuse/fuse-libs, Debian/Ubuntu: libfuse2/libfuse2t64) with a custom import/remove tool via ./manage.sh apps
• Chezmoi-powered: Smart dotfile management with templates and conditional installation
• Easy to extend: Add new distros or package groups with simple YAML files

Quick Start

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

# Run the interactive management menu
./manage.sh

# Or run the installer directly
./manage.sh setup

The interactive installer will:

1. Detect your distribution
2. Choose setup type (Desktop or Terminal)
3. Let you choose package groups to install
4. Install all selected packages
5. Apply dotfiles using Chezmoi
6. Enable required services
7. Set up SSH keys and shell

Package Groups

Group	Description
Hyprland	Hyprland compositor with hypridle, hyprlock, hyprpaper, hyprshot, waybar, rofi, swaync, wlogout, clipboard tooling (cliphist, wl-clipboard) and Wayland helpers
Niri	Niri scrollable tiling compositor with Wayland desktop tools (waybar, rofi, swaync, wlogout, sddm, clipboard, screenshots)
Development	neovim, Cursor, Git tooling (gh, lazygit, delta), containers (docker, docker-compose, lazydocker), build/task tools (cmake, gcc/base-devel, just), and Claude Code with ccstatusline
Gaming	Steam + Discord with performance helpers (mangohud, gamemode)
Multimedia	Media and creation tools (mpv, obs-studio, ffmpeg, ImageMagick, GIMP, Inkscape)
Productivity	File managers (Dolphin + Yazi), thumbnail support (ffmpegthumbnailer, kdegraphics-thumbnailers), BTRFS snapshots (snapper, snap-pac/python3-dnf-plugin-snapper, grub-btrfs), communication/browser apps (Slack, Chrome), archive tools, and themes/icons
AI	AI-powered desktop tools: hyprvoice speech-to-text dictation with local Whisper models

Structure

dotfiles/
├── manage.sh                # Management script (single entry point)
├── tools/
│   ├── setup.sh             # Bootstrap script (installs gum + git, runs installer)
│   └── manage-cursor-extensions.sh # Export/install Cursor extensions list
├── install/
│   ├── installer.sh         # Main interactive installer
│   ├── distros/
│   │   ├── arch.sh          # Arch Linux package functions
│   │   ├── fedora.sh        # Fedora package functions
│   │   └── debian.sh        # Debian/Ubuntu package functions
│   └── lib/
│       ├── common.sh        # Shared utilities
│       ├── detect.sh        # Distro detection
│       ├── services.sh      # Service management
│       └── tree_select.py   # Interactive package selector TUI
├── packages/
│   ├── common.yaml          # Cross-distro tools (zoxide, volta, etc.)
│   ├── arch/
│   │   └── base.yaml        # Arch base packages
│   ├── fedora/
│   │   └── base.yaml        # Fedora base packages
│   ├── debian/
│   │   └── base.yaml        # Debian/Ubuntu base packages
│   └── groups/
│       ├── hyprland.yaml    # Hyprland + Wayland tools
│       ├── niri.yaml        # Niri compositor + Wayland tools
│       ├── development.yaml # Dev tools
│       ├── gaming.yaml      # Gaming packages
│       ├── multimedia.yaml  # Media tools
│       ├── productivity.yaml
│       └── ai.yaml          # AI tools (dictation, Whisper)
├── home/                    # Chezmoi source directory
│   ├── .chezmoiignore       # Conditional dotfile rules
│   ├── dot_config/          # ~/.config files
│   ├── dot_zshrc            # ~/.zshrc
│   └── ...
└── README.md

Cursor Extensions Script

This repo includes a Cursor extensions manager to keep extensions reproducible across machines.

It reads/writes the extension list at home/dot_config/Cursor/extensions.txt.

Usage

# Interactive menu
./manage.sh cursor

# Export currently installed extensions to extensions.txt
./manage.sh cursor export

# Install all extensions from extensions.txt
./manage.sh cursor install

Notes

• Requires the cursor CLI in your PATH.
• install is idempotent: already-installed extensions are skipped/reinstalled safely.

External Apps Helper

This repo includes an external apps helper for:

• importing an AppImage into your desktop launcher
• installing a local .deb, .rpm, or .pkg.tar.* inside a Distrobox container
• exporting the installed app to your host launcher with distrobox-export
• updating that Distrobox-managed app later using saved metadata
• guiding these flows interactively from ./manage.sh apps

Usage

# Open the helper from the manager
./manage.sh apps

# Import an AppImage into the desktop launcher
./manage.sh apps import-appimage ~/Downloads/MyApp.AppImage

# Install a package into a Distrobox container and export it to the host launcher
./manage.sh apps install-distrobox --container ubuntu --package ~/Downloads/app.deb

# Update a previously managed Distrobox app
./manage.sh apps update-distrobox --name app --package ~/Downloads/app-new.deb

# List saved Distrobox app metadata
./manage.sh apps list

Notes

• ./manage.sh apps is a real interactive wizard, not just a help menu.
• The root Manage external apps menu item is shown only on desktop installs where Distrobox is installed.
• File picking starts in ~/Downloads and falls back to $HOME if that folder does not exist.
• Distrobox install prefers choosing from existing containers before falling back to manual entry.
• Distrobox update uses saved managed app records instead of asking you to type the app name.
• install-distrobox tries to auto-detect the new .desktop file after install; if multiple entries are added, pass --app your.desktop.
• Managed Distrobox app metadata is stored under ${XDG_STATE_HOME:-~/.local/state}/dotfiles/external-apps/distrobox/.

Adding a New Distribution

1. Create install/distros/<distro>.sh with package manager functions
2. Create packages/<distro>/base.yaml with package names
3. Add distro-specific packages to packages/groups/*.yaml
4. Update install/lib/detect.sh if needed

Three distro families are already supported: Arch, Fedora, and Debian/Ubuntu (see install/distros/debian.sh for a real example).

Manual Chezmoi Usage

If you previously used GNU Stow, this is the main behavior change to keep in mind:

• Stow mental model: repo files are symlinked into $HOME, so editing the repo is "live" immediately.
• Chezmoi mental model: repo files are the source state and your home directory is the target state. Changes are applied when you run chezmoi apply (or related commands).

First-time setup (manual)

# Initialize chezmoi with this repo
chezmoi init --source=~/dotfiles/home

# Verify source is correct (important)
chezmoi source-path

Daily commands (most useful)

# See what would change before touching your home files
chezmoi diff

# Apply source state to your home directory
chezmoi apply

# Edit a managed file safely (writes back to source state)
chezmoi edit ~/.zshrc

# Check what changed in source state
chezmoi status

# Pull and apply latest changes from your remote dotfiles repo
chezmoi update

Typical workflow after editing this repo

cd ~/dotfiles
git pull
chezmoi diff
chezmoi apply

Can Chezmoi auto-apply?

Yes, but it is not the default behavior.

• Recommended default: keep manual chezmoi diff + chezmoi apply so changes are explicit.
• Possible auto-apply: run a file watcher (e.g. inotifywait/entr) or a user systemd path service that triggers chezmoi apply when files in ~/dotfiles/home change.
• Caveat: fully automatic apply can surprise you during partial edits; many users prefer explicit applies for safer config management.

Post-Installation

After running the installer:

1. Log out and back in for shell changes to take effect
2. Start tmux and press Ctrl+b I to install tmux plugins
3. Add SSH key to GitHub/GitLab (displayed during setup)
4. Hyprland users: Press Super+? to see keybindings
5. Niri users: Log out, choose Niri in your display manager, log back in
6. Dark/light mode: Press Mod+N to toggle between Catppuccin Mocha and Latte
7. Plymouth: Reboot to see the boot splash (if configured during install)

Included Configurations

• Shell: zsh with starship prompt, zoxide, television
• Terminal: kitty
• Editor: Neovim (AstroNvim-based), Cursor
• Git: delta for diffs, lazygit
• Multiplexer: tmux with TPM
• File Manager: yazi, dolphin
• Hyprland: hypridle, hyprlock, hyprpaper, hyprshot, waybar, rofi, swaync, wlogout
• Niri: niri with waybar, rofi, swaync, wlogout (scrollable tiling Wayland compositor)
• AI: hyprvoice dictation with local Whisper speech recognition
• Claude Code: ccstatusline status bar (Catppuccin Powerline theme), WorkTrunk worktree plugin
• AppImage support: Desktop installs set up AppImage support per distro family; terminal installs skip it

Credits

Hyprland configuration originally inspired by ml4w starter kit.

License

MIT License - see LICENSE for details.