Arch Linux Dotfiles Manager
An expert agent for managing a modular Linux dotfiles repository using GNU Stow for symlink management. This skill specializes in dotfiles architecture, ZSH configuration, i3-gaps window management, and theming workflows.
Overview
This skill helps you work with a personal Linux dotfiles repository that uses **GNU Stow** to manage configuration files across multiple tools and applications. Each top-level directory represents an independently installable "stow package" that creates symlinks in your home directory.
Architecture Understanding
Stow Package Structure
When working with this repository:
Each directory (e.g., `git/`, `zsh/`, `tmux/`) is a stow packageFiles inside packages mirror their target directory structureRunning `stow <package>` from `~/.dotfiles` creates symlinks in `$HOME`Example: `git/.gitconfig` becomes `~/.gitconfig` after running `stow git`Files matching `.stow-global-ignore` patterns are never symlinked (DS_Store, README files, etc.)ZSH Special Case
The `zsh/` package has unique structure requirements:
Actual dotfiles live in `zsh/configs/` subdirectoryInstall command: `cd ~/.dotfiles/zsh && stow configs -t ~/``.zshrc` sources modular configuration from: - `~/.dotfiles/zsh/aliases/*.zsh` (command aliases by category)
- `~/.dotfiles/zsh/exports/*.zsh` (environment variables)
- `~/.dotfiles/zsh/plugins/*.zsh` (plugin configurations)
Common Tasks
Installing Configuration Packages
**Single package installation:**
```bash
cd ~/.dotfiles && stow <package-name>
```
**Full installation (all packages):**
```bash
cd ~/.dotfiles && \
stow i3 mopidy cava ncmpcpp stow wal git ssh tmux picom dunst xresources && \
cd zsh && stow configs -t ~/
```
Handling Stow Conflicts
If stow warns about existing files, rename them first:
```bash
mv ~/.gitconfig ~/.gitconfig.old
stow git
```
Adding New Configuration
When creating new ZSH aliases or exports:
1. Add new `.zsh` files to appropriate subdirectories:
- Aliases: `zsh/aliases/<category>.zsh`
- Environment variables: `zsh/exports/<tool>.zsh`
- Plugin configs: `zsh/plugins/<plugin>.zsh`
2. Restow: `cd ~/.dotfiles/zsh && stow configs -t ~/`
Tool Stack & Integrations
Core Components
**Shell**: zsh + prezto framework**Terminal**: urxvt + tmux (256color, mouse enabled)**Window Manager**: i3-gaps + polybar (status bar) + dunst (notifications) + picom (compositor)**Editor**: neovim (aliased as `vim`/`vi`), VSCode**Git**: GPG signing enabled, delta for diffs, `main` as default branch**Theming**: pywal (generates colorschemes from wallpapers)**Python**: pyenv + pyenv-virtualenv**Music**: cava visualizer + mopidy playerIntegration Points
**pywal**: Colors loaded in `.zshrc` from `~/.cache/wal/`**atuin**: Shell history sync initialized in `.zshrc`**fzf**: Fuzzy finder integration sourced if available**kubectl**: Shell completion enabled if binary exists**prezto**: ZSH framework initialization happens first in `.zshrc`Custom Aliases & Functions
Key shortcuts defined in this configuration:
`ls`/`ll`/`l` → exa with icons and directory-first sorting`man` → tldr (simplified man pages)`pushme <message>` → git add, commit, push to current branch in one command`desktop-mode`/`laptop-mode` → xrandr + monitor + brightness presets`gpgd <input> <output>` → decrypt GPG filesConfiguration Organization Patterns
XDG Base Directory Compliance
Many packages use `.config/` subdirectories:
`nvim/.config/nvim/` → `~/.config/nvim/``i3/.config/i3/` → `~/.config/i3/`Modular Configuration Files
**ZSH aliases**: Split by purpose (arch.zsh, dbt.zsh, git.zsh, k8s.zsh, general.zsh)**ZSH exports**: Each tool/environment in separate file (pyenv.zsh, go.zsh, browser.zsh)**tmux configs**: Split into keybinds.tmux, settings.tmux, statusbar.tmux, plugins.tmuxPre-commit Hooks
Security-focused hooks run automatically on commit/push:
Detects private keys and AWS credentialsValidates YAML/JSON syntaxChecks for merge conflictsEnforces consistent formatting (trailing whitespace, EOF newlines, no tabs)**Manual execution:**
```bash
pre-commit run --all-files
```
Requirements
Essential Dependencies
i3-gaps, polybar, dunst, picomNerdFonts, tamzen fonttmux + tpm (tmux plugin manager)zsh + preztoGNU StowOptional Enhancements
pywal (dynamic colorscheme generation)betterlockscreen (lockscreen manager)cava (audio visualizer)feh (wallpaper setter)Best Practices
1. **Always run stow from repository root** (`~/.dotfiles`)
2. **Use conventional commit messages** (pre-commit hooks enforce quality)
3. **Add new ZSH configs as separate files** in appropriate subdirectories
4. **Backup existing configs before stowing** to avoid conflicts
5. **Font references are critical** for UI rendering (NerdFonts, tamzen, bitmap fonts)
Platform Notes
This configuration is **Arch Linux-focused** (package manager commands, binary paths)Shell path defaults to `/usr/bin/zsh`Theming relies on pywal colorscheme generation from wallpapers