dotfiles

Cross-platform dotfiles managed with GNU Stow: a Linux/Hyprland desktop plus agent configs (pi) that work on macOS too.

AGENTS.md documents the layout for coding agents (pi reads it automatically).

Layout

Everything that gets linked into $HOME lives under home/:

dotfiles/
├── home/                     # Mirrors ~
│   ├── .config/
│   │   ├── hypr/             # Hyprland, scripts, keybinds (Linux)
│   │   ├── waybar/           # Status bar (Linux)
│   │   ├── kitty/            # Terminal
│   │   ├── rofi/             # App launcher / menus (Linux)
│   │   ├── btop/             # System monitor
│   ├── .local/share/applications/
│   └── .pi/                     # pi agent: settings.json + themes/ (see home/.pi/AGENTS.md)
├── wallpapers/               # Linked to ~/Pictures/wallpapers on install
├── install.sh
├── doctor.sh                 # Health check: symlinks, configs, git state
├── packages.txt              # apt packages (Linux only)
└── AGENTS.md

install.sh links cross-platform agent configs straight into $HOME (pi's settings.json, themes/, extensions/) — no dependencies needed. On Linux it then uses GNU Stow for the desktop configs and installs packages.txt via apt. On macOS stow is optional: without it you get an agent-only install.

A generated stow/ directory (gitignored) holds Stow packages; edits in home/... apply immediately via the symlinks. Re-run ./install.sh after adding new config directories.

Other machines / agent-only setups

The layout is OS-agnostic — everything under home/ mirrors $HOME, and the agent config (pi) uses the same paths on macOS and Linux:

git clone git@github.com:bautistaaa/dotfiles.git ~/dotfiles
cd ~/dotfiles
./install.sh      # links agent configs; desktop configs need `brew install stow`

Still needed per machine (not captured here): node via nvm (nvm alias default <version> — pi is installed under the nvm-managed node), then npm install -g @earendil-works/pi-coding-agent. Verify with ./doctor.sh.

Fresh machine setup

git clone git@github.com:YOUR_USER/dotfiles.git ~/dotfiles
cd ~/dotfiles
./install.sh

Skip apt installs if packages are already installed:

SKIP_PACKAGES=1 ./install.sh

macOS: brew install stow first; apt is skipped automatically.

After install

1. Log into Hyprland
2. Launch waybar: ~/.config/waybar/launch.sh

Wallpapers live in wallpapers/ in the repo and are linked to ~/Pictures/wallpapers on install.

Keybinds (quick reference)

Binding	Action
Super+Return	Terminal (kitty)
Super+E	Yazi (new workspace)
Super+G	Chrome (new workspace)
Super+X	btop (new workspace)
Super+[ / Super+]	Previous / next workspace
Super+1–6	Go to workspace
Super+Shift+1–6	Move window to workspace

Updating configs

Edit files in home/..., then re-run install if you add new packages:

cd ~/dotfiles
SKIP_PACKAGES=1 ./install.sh

Or restow manually:

cd ~/dotfiles
./install.sh

Push to GitHub

cd ~/dotfiles
git init
git add .
git commit -m "Initial dotfiles"
gh repo create dotfiles --private --source=. --push

Use a private repo unless you have audited for secrets.

Optional: machine-specific overrides

Create untracked files under local/ or add a host profile later if laptop/desktop configs diverge.