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.

📍 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 can also run inside Neovim via the [claude-code.nvim][claude-code-nvim] plugin, which is how I use it most of the time during development.

Skills

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

| Skill | Purpose | | ----- | ------- | | /bootstrap-prd | Scaffold PRD-driven development infrastructure into a new project | | /checkpoint | Quick status update — what's done, in progress, and blocked | | /commit | Analyze diffs, split into logical commits, Conventional Commits format | | /create-pr | Create a PR with auto-linked issues and formatted description | | /debrief | Comprehensive walkthrough of recent work with architecture rationale | | /plan-phase | Draft implementation plan and create GitHub issues (no code written) | | /qa-handoff | Prepare a hands-on QA testing guide for a completed PRD phase | | /resolve-issue | Structured workflow for resolving a GitHub issue end-to-end | | /review-pr | Read-only PR review with severity-ranked findings | | /setup-sprint | Create parallel Git worktrees for a batch of labeled issues | | /sprint-issue | Streamlined variant for small, well-scoped issues | | /update-deps | Safe dependency updates with testing between each category |

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-hugo       # base + Hugo overlay
cc-js         # base + JavaScript/Node overlay
cc-dotfiles   # base + dotfiles overlay
cc-sprint     # all-inclusive sprint preset
cc-default    # base only
cc-clean      # remove project settings
cc-perms      # show active permission counts

Presets live in claude/.claude/presets/ with a [README][presets-readme] explaining the design.

Safety

• Hooks block rm -rf patterns and log all Bash commands
• Deny rules prevent force push, hard reset, sudo, and credential reads
• Sandbox mode enabled by default with filesystem and network restrictions

Shell Abbreviations

Zsh abbreviations for quick access (via [zsh-abbr][zsh-abbr]):

| Abbreviation | Expands to | | ------------ | ---------- | | cl | claude | | clr | claude --resume | | clc | claude --continue | | clup | claude update |

See zsh/.config/zsh-abbr/abbreviations.zsh for the full set (clsp, clh, clv, clp, clcp, clmcp).

Other Configuration

• CLAUDE.md — Global development philosophy and coding standards applied across all projects
• cheatsheet.md — Quick reference for keyboard shortcuts, commands, and context management tips
• starship.toml — Custom [Starship prompt][starship-claude] showing model, context window status, and token cost
• .mcp.json — [Context7][context7] MCP server for querying up-to-date library documentation

About Neovim Distributions

[!TIP] TL;DR: Just install [LazyVim][lazyvim]💤

📺 [Zero to IDE with LazyVim][zero-to-ide-lazyvim-video]

Back in the day if you wanted to use Vim (and later Neovim) you had to code a ton of configuration on your own. With Vim we got Vimscript 🤢, but then came Neovim which brought us Lua 🤩. I went from ye olde crunchy .vimrc to the more adventurous init.vim to the blessed path of init.lua. 😇

Meanwhile, there were the