Dotfiles

Opinionated dotfiles managed with GNU Stow. Covers macOS and Arch Linux with configs for Neovim, tmux, Ghostty, Hyprland + Waybar/Rofi, and more. 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 ghostty aerospace borders

Arch Linux:

sudo pacman -S --needed stow neovim tmux ghostty hyprland hyprlock hypridle 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 — Primary Neovim 0.12+ config using the native package manager (vim.pack).
• nvim-legacy/.config/nvim — Legacy Neovim config for older distros, using lazy.nvim.
• 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

• Terminal
  • 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, and Hypridle.
  • archlinux/.config/waybar — Waybar config + Catppuccin theme.
  • archlinux/.config/rofi — Rofi launcher.
• 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

• Ghostty and Waybar use Catppuccin Mocha.
• Primary Neovim (nvim/) uses tokyonight; legacy Neovim (nvim-legacy/) uses Rose Pine.
• Fonts: Install a Nerd Font and set it in your terminal for icons and glyphs.

---

Neovim Notes

Two Neovim configs are available:

nvim — primary config for Neovim 0.12+, using the native vim.pack package manager.

nvim-legacy — fallback config for older distros, using lazy.nvim.

Use nvim-legacy on systems where Neovim 0.12+ is not available from the distro or package manager.

Switching to nvim-legacy

If you already have the primary nvim module stowed, unstow it first, then stow nvim-legacy:

stow -D nvim
stow nvim-legacy

To go back to the primary config:

stow -D nvim-legacy
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 tmux borders neovim aerospace ghostty

Arch Linux (pacman):

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

Some Hyprland or community packages may be available via yay.