Dotfiles

Personal macOS dotfiles for Juan Pinto, managed with GNU Stow. There's no bootstrap script or install target—setup is the handful of manual steps below.

This is my actual day-to-day setup, not a general-purpose framework, so it comes with strong personal opinions (Everforest theme everywhere, specific keybindings, an AI-coding-agent-heavy workflow via pi) and machine-specific assumptions (macOS, Homebrew, zsh). It's public for reference—browse it for ideas or fork what's useful, but treat it as inspiration rather than something to install wholesale.

What's inside

Area	Tool(s)
Shell	zsh (.zshrc), Starship prompt
Terminal	WezTerm, tmux
Editor	Neovim (built-in vim.pack, no plugin-manager framework)
Window management	AeroSpace, sketchybar
Keyboard remapping	Karabiner-Elements
File manager	Yazi
System monitor	btop
Email	aerc
AI coding agent	pi
Linting/formatting	Ruff (Python), StyLua (Lua), markdownlint
Diff/review	hunk

Prerequisites

• macOS
• Homebrew
• GNU Stow: brew install stow

Setup on a new machine

1. Clone the repo to ~/.dotfiles:

   git clone https://github.com/juandpinto/dotfiles.git ~/.dotfiles
   cd ~/.dotfiles

2. Initialize submodules (fzf-git.sh and tmux's plugin manager, TPM):

   git submodule update --init

3. Stow everything into $HOME:

   stow -t ~ .

   .stow-local-ignore keeps .git, .gitignore, .DS_Store, and the root README.md/AGENTS.md/package-lock.json out of the link; those stay in the repo instead of linking into $HOME.

4. If ~/.config/<tool> already exists as a real directory before you stow, rather than being created fresh by Stow, Stow folds into it and links files individually instead of linking the whole directory. That's expected, and it's exactly what happens with ~/.config/pi/agent—see below.

pi agent config

~/.config/pi/agent mixes stowed config (AGENTS.md, extensions/, models.json, settings.json, skills/) with files pi manages itself (auth.json, sessions/, npm/, git/). Those four are gitignored and intentionally not part of this repo: npm/ and git/ are pi's own package install/clone directories for whatever's listed in settings.json's packages array, and auth.json/sessions/ hold credentials and session history that shouldn't be shared across machines.

On a genuinely fresh machine, no manual step is needed for npm//git/: just launch pi (or run pi list) after stowing, and it reads the already-stowed settings.json and installs any missing packages entries into fresh local directories automatically.

If you're migrating a machine that still has ~/.config/pi/agent/npm or ~/.config/pi/agent/git symlinked into this repo from before this convention existed, fix it once with:

test -L ~/.config/pi/agent/npm && rm ~/.config/pi/agent/npm
test -L ~/.config/pi/agent/git && rm ~/.config/pi/agent/git
rm -rf ~/.dotfiles/.config/pi/agent/npm ~/.dotfiles/.config/pi/agent/git
pi list   # or just launch pi; it reinstalls packages from settings.json

Then confirm both are real directories, not symlinks:

readlink ~/.config/pi/agent/npm   # prints nothing once fixed
readlink ~/.config/pi/agent/git   # prints nothing once fixed

Other first-launch steps

• Neovim: uses the built-in vim.pack plugin manager; plugins install automatically the first time you launch nvim.
• tmux: plugins install via TPM; press prefix + I inside tmux on first use. .config/tmux/plugins/* other than tpm itself is gitignored—TPM installs the rest at runtime, they're not vendored here.

See AGENTS.md for more detail on the repo's structure and conventions.