Dotfiles

Opinionated dotfiles managed with GNU Stow. Covers macOS and Arch Linux with configs for Neovim, tmux, Kitty/Ghostty, Hyprland + Waybar/Rofi, and more. Theme: Catppuccin. Requires a Nerd Font.

---

Quick Start

1. Install prerequisites

macOS (Homebrew):

# Install Homebrew if needed (see https://brew.sh)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install stow neovim tmux kitty ghostty iterm2 aerospace borders

Arch Linux:

sudo pacman -S --needed stow neovim tmux kitty ghostty hyprland hyprlock hypridle hyprpaper waybar rofi
# Some Hyprland extras might require yay: https://github.com/Jguer/yay

2. Clone and stow what you want

git clone git@github.com:584973/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Dry-run to preview changes
stow -nvt ~ nvim tmux

# Apply symlinks into $HOME
stow nvim tmux

Tip: Run stow -D <module> to remove symlinks and stow -R <module> to restow after changes.

3. Install a Nerd Font and select it in your terminal. Fonts: https://www.nerdfonts.com/

---

Modules

Each top-level folder mirrors where files should live under $HOME. Stow only what you use.

• nvim/.config/nvim — Neovim 0.9+ with lazy.nvim; plugins auto-install on first launch.
• pack-nvim/.config/nvim — Neovim 0.12+ using the native package manager (vim.pack); minimal alternative to the lazy.nvim config.
• tmux/.tmux.conf — tmux configuration. Install TPM to enable plugins:

  git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
  # Then press prefix + I inside tmux to install plugins

• Terminals
  • kitty/.config/kitty — Kitty config.
  • ghostty/.config/ghostty — Ghostty config.
• macOS
  • macos/.config/aerospace — Aerospace tiling window manager.
  • macos/.config/borders — Window borders.
• Arch Linux / Wayland
  • archlinux/.config/hypr — Hyprland, Hyprlock, Hypridle, Hyprpaper.
  • archlinux/.config/waybar — Waybar config + Catppuccin theme.
  • archlinux/.config/rofi — Rofi launcher.
• Backgrounds
  • backgrounds/.config/backgrounds — Wallpapers used by Hyprpaper.
• Editors
  • ideavim/.ideavimrc — JetBrains IdeaVim configuration.
  • vim/.vimrc — Plain Vim configuration.
• Pi Agent
  • pi/.pi/agent/settings.json — Pi coding agent preferences (packages, default model, provider, thinking level). Does not include API keys or session data.

---

Stow Basics

This repository is structured for Stow: the directory tree under each module matches its location relative to $HOME. For example, nvim/.config/nvim stows to ~/.config/nvim.

• Preview: stow -nvt ~ <module>
• Install: stow <module>
• Remove: stow -D <module>
• Restow: stow -R <module>

If symlinks look wrong, ensure you run stow from the repo root and that the module mirrors your desired location under $HOME.

---

Adopting Existing Configs

Use --adopt to pull your existing config files into this repo and replace them with symlinks in one step.

Step-by-step:

# 1. Create the matching path inside the module
mkdir -p ~/dotfiles/nvim/.config/nvim

# 2. Copy (or move) your existing file into place
cp ~/.config/nvim/init.lua ~/dotfiles/nvim/.config/nvim/init.lua

# 3. From the repo root, adopt: stow moves the file into the repo
#    and replaces the original with a symlink
cd ~/dotfiles
stow --adopt nvim

# 4. Review what changed, then commit
git diff
git add -p
git commit -m "(nvim) adopt existing init.lua"

Warning: --adopt overwrites files already in the repo with whatever is on disk. Run git diff after adopting so you can spot and revert any unintended changes.

Adopting everything at once (use with care):

stow --adopt .
git diff        # review before committing

---

Copying to a Remote Machine

Use scp to copy individual configs over SSH without needing stow on the remote:

# Single files
scp tmux/.tmux.conf vim/.vimrc user@host:~

# Directory (e.g. Neovim)
scp -r nvim/.config/nvim user@host:~/.config/

---

Theme & Fonts

• Theme: Catppuccin across terminals, Waybar, and Neovim.
• Fonts: Install a Nerd Font and set it in your terminal for icons and glyphs.

---

Neovim Notes

Two Neovim configs are available:

nvim — Neovim 0.9+, uses lazy.nvim which bootstraps automatically on first launch.

pack-nvim — Neovim 0.12+ only, uses the native vim.pack package manager. More minimal, no third-party plugin manager required.

Switching from nvim to pack-nvim

If you already have nvim stowed, unstow it first, then stow pack-nvim:

stow -D nvim
stow pack-nvim

To go back:

stow -D pack-nvim
stow nvim

---

Pi Agent

The pi/ module tracks your agent preferences but not sensitive runtime files (see .gitignore).

First-time setup on a new machine

1. Install the pi CLI (however you originally installed it — e.g. Homebrew, npm, or manual install).
2. Stow the config:

   stow pi

3. Create your local auth file with your API key:

   mkdir -p ~/.pi/agent
   nvim ~/.pi/agent/auth.json

   Example auth.json:

   {
     "your-provider": {
       "type": "api_key",
       "key": "your-key-here"
     }
   }

4. Launch pi — packages from settings.json should auto-install on first run.

Security note: auth.json, sessions/, bin/, extensions/, and logs/ are all ignored. Never commit API keys.

Troubleshooting

Wrong stow target — always run stow from the repo root so it resolves $HOME correctly:

cd ~/dotfiles
stow nvim

Conflict: file already exists — stow refuses to overwrite real files. Either adopt it (see above), back it up, or remove it first:

mv ~/.config/nvim/init.lua ~/.config/nvim/init.lua.bak
stow nvim

Broken symlinks — if a symlink points nowhere (e.g. after moving the repo), restow to recreate:

stow -D nvim    # remove all symlinks for this module
stow nvim       # lay them down again

Find all broken symlinks under $HOME:

find ~ -maxdepth 5 -xtype l 2>/dev/null

Full reset for a module — remove symlinks, wipe the module's target directory, and start clean:

stow -D nvim
rm -rf ~/.config/nvim
stow nvim

---

OS Package References

macOS (Homebrew):

brew install iterm2 tmux borders neovim aerospace ghostty kitty

Arch Linux (pacman):

sudo pacman -S tmux neovim hyprland hyprlock hypridle waybar kitty ghostty hyprpaper rofi

Some Hyprland or community packages may be available via yay.