dotfiles

Personal macOS dotfiles organized as installable packages. Each directory under packages/ mirrors the path it should occupy under $HOME, and install.sh links those packages with GNU Stow.

Installation

Prerequisites

sudo softwareupdate -i -a
xcode-select --install

Quick install

The default checkout location is ~/.dotfiles:

git clone https://github.com/kalupas226/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh

install.sh prompts before running official remote installer scripts. To skip those prompts:

./install.sh --skip-confirmation

To run only part of the installation, pass one or more targets. Targets always run in installation order:

./install.sh link
./install.sh brew mise

Available targets are brew, link, tpm, mise, and claude. Use all, or omit targets, to run the full installation. Selected targets do not automatically run missing prerequisites; for example, link reports an error if GNU Stow is unavailable.

Restart your terminal, or run exec zsh, after installation.

What install.sh Does

• Installs Homebrew if missing
• Runs brew bundle -v --file=Brewfile
• Links package dotfiles into $HOME with stow --no-folding
• Installs TPM if missing
• Activates mise and runs mise install
• Installs Claude Code if missing
• Prints manual setup reminders

After the first install, use the helper in ~/.local/bin for routine maintenance:

dotfiles outdated

Post-Install Steps

Some tools need one-time manual setup after install.sh.

The current checklist is printed by install.sh at the end of the install so the manual steps have one source of truth.

Maintenance

• Check managed updates: dotfiles outdated
• Refresh update metadata before checking: dotfiles outdated --refresh
• Check a single source: dotfiles outdated brew, dotfiles outdated mise, or dotfiles outdated sheldon
• Diagnose local symlink health: dotfiles doctor
• Install or relink everything: dotfiles install
• Run selected installation targets: dotfiles install link or dotfiles install brew mise
• Generate Claude Code settings: dotfiles claude-settings
• Node.js is pinned in packages/mise/.config/mise/config.toml
• Homebrew packages are defined in Brewfile
• Manual setup reminders are maintained in install.sh
• Neovim plugins are locked in packages/nvim/.config/nvim/lazy-lock.json
• Git identity defaults to GitHub noreply; override per machine with ~/.gitconfig.local
• Git and lazygit render diffs with git-delta (installed via Brewfile)
• Prefer project-local devDependencies, npm dlx/npx, or Homebrew over global npm installs

If brew bundle or mise install fails mid-run, fix the cause and rerun dotfiles install brew or dotfiles install mise. Running dotfiles install still reruns the full installation.

If Stow reports conflicts from legacy symlinks created by older versions of install.sh, run:

scripts/migrate-legacy-links-to-stow.sh --dry-run
scripts/migrate-legacy-links-to-stow.sh
./install.sh

Claude Code

• ~/.claude/settings.json is generated manually with dotfiles claude-settings
• packages/claude/.claude/_settings-source/shared.json is repo-managed
• Add machine-specific Claude settings as any other *.json file in ~/.claude/_settings-source/
• Claude Code uses packages/claude/.claude/statusline-command.sh for a compact two-row statusline

tmux

• tmux opens shells, panes, and lazygit from the active pane's current directory
• tmux libexec helpers provide the project picker, the file reference picker, and the scrollback text picker
• Interactive zsh auto-starts a home tmux session with a main window, except in Claude, Codex, and VS Code terminals

Repository Structure

.
├── Brewfile
├── install.sh
├── packages/
│   ├── aerospace/  # AeroSpace configuration
│   ├── bin/        # User-facing helpers installed into ~/.local/bin
│   ├── claude/     # Claude Code settings source and statusline
│   ├── git/        # Git configuration
│   ├── karabiner/  # Karabiner-Elements configuration
│   ├── lazygit/    # Lazygit configuration
│   ├── mise/       # mise tool pins
│   ├── npm/        # npm defaults
│   ├── nvim/       # Neovim configuration
│   ├── sheldon/    # zsh plugin pins
│   ├── starship/   # Starship prompt
│   ├── tmux/       # tmux configuration and tmux-only libexec helpers
│   ├── wezterm/    # WezTerm configuration
│   └── zsh/        # zsh startup files and helpers
├── scripts/        # Maintenance, diagnostics, and update-check scripts
├── skills/         # Shared Agent Skills
└── tests/          # Shell regression tests

Useful references:

• skills/README.md - shared Agent Skills in this repo
• AGENTS.md - guidance for AI coding agents working in this repository