My Dotfiles for macOS

![dotfiles screenshot][screenshot]

🤩 Highlights

• [Neovim][neovim] editor configured with [LazyVim][lazyvim]💤
• [Starship][starship] prompt
• [Zsh][zsh] shell with [zsh-abbr][zsh-abbr] for abbreviations
• Flexible, terminal-based dev environment with [ghostty][ghostty] 👻 + [Tmux][tmux]!
• [Claude Code][claude-code] with custom skills, permission presets, and safety hooks
• Fast, idempotent setup with [GNU Stow][gnu-stow]
• New Mac bootstrap based on thoughtbot's [Laptop][laptop]
• Support for both Apple Silicon and Intel Macs

[!NOTE] This project previously supported [Fish shell][fish] alongside Zsh. Fish support was removed in [PR #135][pr-135] (f158de9). If you were using the Fish configuration, you can reference that PR to see what changed or recover code for your own setup.

⚡️ Quick Setup

Make sure macOS is up to date and you have installed the required software.

Clone this repo.

git clone https://github.com/joshukraine/dotfiles.git ~/dotfiles

Read the setup script and check available options.

less ~/dotfiles/setup.sh
~/dotfiles/setup.sh --help

Preview what the setup script will do (dry-run mode).

~/dotfiles/setup.sh --dry-run

Run the setup script.

~/dotfiles/setup.sh

✅ Prerequisites

The dotfiles assume you are running macOS with (at minimum) the following software pre-installed:

• [Git][git]
• [Homebrew][homebrew] (including [coreutils][coreutils])
• [asdf][asdf]
• [Ruby][ruby]
• [Node.js][nodejs]
• [Zsh][zsh]
• [Neovim][neovim]
• [Starship][starship]

All of the above and more are installed with my fork of [Laptop][joshuas-laptop].

🌟 New Mac Bootstrap

This is what I would do if I bought a new Mac computer today. The steps below assume you have already completed the basics:

• Log in to iCloud
• Check for software updates
• [Install Xcode Command Line Tools][install-clt]

💻 1. Run my fork of thoughtbot's Laptop

▹ [github.com/joshukraine/laptop][joshuas-laptop]

Download the mac script:

curl --remote-name https://raw.githubusercontent.com/joshukraine/laptop/main/mac

Download .local.laptop for additional customizations:

curl --remote-name https://raw.githubusercontent.com/joshukraine/dotfiles/master/laptop/.laptop.local

Review both scripts before proceeding:

less mac

less .laptop.local

Execute the mac script:

sh mac 2>&1 | tee ~/laptop.log

I've made the following changes to my fork of Laptop:

• Install asdf via git instead of Homebrew
• Comment out Heroku-related code
• Comment out unused Homebrew taps and formulae

It is worth noting that the Laptop script (mac) is idempotent and can be safely run multiple times to ensure a consistent baseline configuration.

⚠️ 2. Check for Stow conflicts

The dotfiles setup.sh script uses [GNU Stow][gnu-stow] to symlink all the config files to your $HOME directory. If you already have an identically-named file/directory in $HOME (e.g. ~/.zshrc leftover from installing Laptop), this will cause a conflict, and Stow will (rightly) abort with an error.

The setup script will try to detect and backup these files ahead of Stow, but it's still a good idea to check your $HOME directory as well as $HOME/.config and $HOME/.local/bin.

On a fresh machine, setup.sh also pre-creates ~/.claude as a real directory so Stow links the Claude config files individually instead of folding the whole directory into one symlink (which would route Claude Code's runtime state into the repo). If you forked before this behavior existed and see Claude runtime files appearing in git status, see Troubleshooting: ~/.claude folding.

📍 3. Clone and setup the dotfiles

Clone

git clone https://github.com/joshukraine/dotfiles.git ~/dotfiles

Read and preview

less ~/dotfiles/setup.sh
~/dotfiles/setup.sh --help
~/dotfiles/setup.sh --dry-run  # Preview changes without applying them

Setup

~/dotfiles/setup.sh

If you do encounter Stow conflicts, resolve these and run setup again. The script is idempotent, so you can run it multiple times safely.

⚡️ 4. Install Zap

[Zap][zap] describes itself as a "minimal zsh plugin manager that does what you expect."

▹ [zapzsh.com][zap]

[!IMPORTANT] After copying/pasting the install command for Zap, be sure to add the --keep flag to prevent Zap from replacing you existing .zshrc file.

🍺 5. Install remaining Homebrew packages

Review the included Brewfile and make desired adjustments.

less ~/Brewfile

Install the bundle.

brew bundle install

🛠️ 6. Complete post-install tasks

• Launch LazyVim (nvim) and run [:checkhealth][checkhealth]. Resolve errors and warnings. Plugins should install automatically on first launch.
• Add personal data as needed to *.local files such as ~/.gitconfig.local, ~/.laptop.local.
• (Optional) Set up [1Password CLI][1p-cli-start] for managing secrets.
• (Optional) Set up [1Password SSH key management][1p-cli-ssh].
• Install Tmux plugins with <prefix> + I (https://github.com/tmux-plugins/tpm)

Zsh Setup

Zsh is now the default shell on macOS. However, it's helpful to add an entry enabling the Homebrew version of Zsh (/opt/homebrew/bin/zsh on Apple Silicon, /usr/local/bin/zsh on Intel) instead of the default (/bin/zsh) version.

Ensure that you have Zsh from Homebrew. (which zsh) If not:

brew install zsh

Add Zsh (Homebrew version) to /etc/shells:

# Apple Silicon Macs:
echo /opt/homebrew/bin/zsh | sudo tee -a /etc/shells

# Intel Macs:
echo /usr/local/bin/zsh | sudo tee -a /etc/shells

# Or use this universal command:
echo $(which zsh) | sudo tee -a /etc/shells

Set it as your default shell:

chsh -s $(which zsh)

Install [Zap][zap].

Restart your terminal.

Abbreviations

One of the best ideas I picked up from using Fish shell is abbreviations over aliases. [zsh-abbr][zsh-abbr] brings this functionality to Zsh.

Abbreviations are managed directly in zsh/.config/zsh-abbr/abbreviations.zsh. You can edit this file directly, or use the abbr add/abbr remove commands in your shell.

Smart Git Functions

The configuration includes intelligent git functions that automatically detect your main branch:

• gpum - Push current branch to origin with upstream tracking
• grbm - Rebase on main/master
• gcom - Checkout main/master
• gbrm - Remove branches merged into main/master

These functions work with both main and master branch names automatically.

Claude Code

[Claude Code][claude-code] is Anthropic's CLI tool for AI-assisted development. This repo includes a full configuration under the claude/ directory, stowed to ~/.claude/.

[!TIP] Claude Code pairs well with [Neovim][neovim] via the [sidekick.nvim][sidekick-nvim] plugin, which is how I use it most of the time during development. My preferred layout runs Claude as a sibling tmux pane (60% editor / 40% Claude) rather than nested inside the editor — see [Claude Code + Neovim][claude-code-neovim] for the setup, the reasoning, and how sidekick sends editor context across panes.

Skills

Custom [skills][agent-skills] provide structured workflows for the full development lifecycle:

Permission Presets

Composable permission presets control what Claude Code is allowed to do in each project. A base preset covers universal operations (git, file editing, Unix tools), and framework overlays add project-specific tooling.

cc-rails      # base + Rails overlay
cc-