- Neovim editor configured with LazyVim💤
- Starship prompt
- Zsh shell with zsh-abbr for abbreviations
- Flexible, terminal-based dev environment with ghostty 👻 + Tmux!
- Claude Code with custom commands, permission presets, and safety hooks
- Fast, idempotent setup with GNU Stow
- New Mac bootstrap based on thoughtbot's Laptop
- Support for both Apple Silicon and Intel Macs
Note
This project previously supported Fish shell alongside Zsh. Fish support was removed in 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.
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 ~/dotfilesRead the setup script and check available options.
less ~/dotfiles/setup.sh
~/dotfiles/setup.sh --helpPreview what the setup script will do (dry-run mode).
~/dotfiles/setup.sh --dry-runRun the setup script.
~/dotfiles/setup.shThe dotfiles assume you are running macOS with (at minimum) the following software pre-installed:
All of the above and more are installed with my fork of Laptop.
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
▹ github.com/joshukraine/laptop
Download the mac script:
curl --remote-name https://raw.githubusercontent.com/joshukraine/laptop/main/macDownload .local.laptop for additional customizations:
curl --remote-name https://raw.githubusercontent.com/joshukraine/dotfiles/master/laptop/.laptop.localReview both scripts before proceeding:
less macless .laptop.localExecute the mac script:
sh mac 2>&1 | tee ~/laptop.logI'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.
The dotfiles setup.sh script uses 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.
Clone
git clone https://github.com/joshukraine/dotfiles.git ~/dotfilesRead and preview
less ~/dotfiles/setup.sh
~/dotfiles/setup.sh --help
~/dotfiles/setup.sh --dry-run # Preview changes without applying themSetup
~/dotfiles/setup.shIf you do encounter Stow conflicts, resolve these and run setup again. The script is idempotent, so you can run it multiple times safely.
Zap describes itself as a "minimal zsh plugin manager that does what you expect."
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.
Review the included Brewfile and make desired adjustments.
less ~/BrewfileInstall the bundle.
brew bundle install- Launch LazyVim (
nvim) and run:checkhealth. Resolve errors and warnings. Plugins should install automatically on first launch. - Add personal data as needed to
*.localfiles such as~/.gitconfig.local,~/.laptop.local. - (Optional) Set up 1Password CLI for managing secrets.
- (Optional) Set up 1Password SSH key management.
- Install Tmux plugins with
<prefix> + I(https://github.com/tmux-plugins/tpm)
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 zshAdd 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/shellsSet it as your default shell:
chsh -s $(which zsh)Install Zap.
Restart your terminal.
One of the best ideas I picked up from using Fish shell is abbreviations over aliases. 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.
The configuration includes intelligent git functions that automatically detect your main branch:
gpum- Push current branch to origin with upstream trackinggrbm- Rebase on main/mastergcom- Checkout main/mastergbrm- Remove branches merged into main/master
These functions work with both main and master branch names automatically.
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 plugin, which is how I use it most of the time during development.
Slash commands provide structured workflows for the full development lifecycle:
| Command | 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 |
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 countsPresets live in claude/.claude/presets/ with a README explaining the design.
- Hooks block
rm -rfpatterns 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
Zsh abbreviations for quick access (via 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).
CLAUDE.md— Global development philosophy and coding standards applied across all projectscheatsheet.md— Quick reference for keyboard shortcuts, commands, and context management tipsstarship.toml— Custom Starship prompt showing model, context window status, and token cost.mcp.json— Context7 MCP server for querying up-to-date library documentation
Tip
TL;DR: Just install LazyVim💤
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 VS Code boys across the fence, bragging about their fancy icons, shiny tabs, and the oh-so-cool LSP. I confess, I even tried VS Code for a bit. That didn't last long. 😬
But Neovim has caught up. And wow have they. caught. up. Not only do we have native LSP support in Neovim (have had for a while now — v0.5), but we are solidly in the era of pre-baked Neovim distributions that are really challenging the notion of Vim/Neovim as austere, command-line editors. (I will say that I think we owe a lot to VS Code for raising the bar here. But I'm still glad I'm with Neovim. 😉)
If you want a quick primer on Neovim distros, check out the YouTube video below. I started with LunarVim (my first entry into distro-land) and now I'm with LazyVim and the Folke gang. Bottom line: you can still config Neovim from scratch if you want to, but you can get a HUGE head-start by just grabbing a distro and tweaking it to your needs.
📺 I tried Neovim Distributions so you don't have to
Boy, when I reminisce about the days of writing PHP for Internet Explorer in BBEdit...
Over the years, I've branched out to explore a variety of mono-spaced fonts, both free and premium. Here is a list of my favorites.
Included in my Brewfile and installed by default via Homebrew Cask Fonts
- Cascadia Code
- Fira Code
- Hack
- JetBrains Mono
- Monaspace Argon
- Monaspace Neon
- Symbols Nerd Font Mono (for icons only)
You have to give people money if you want these. 🤑
I first discovered ligatures through Fira Code, which IMHO is probably the king of programming fonts. After using Fira Code, it's hard to go back to a sans-ligature typeface. Therefore all the fonts I've included in my fave's list do include ligatures, although some have more than others.
Note
Operator Mono does not include ligatures but can be easily patched to add them.
Back in the day, I started using the VimDevicons plugin so I could have fancy file-type icons in Vim. (Remember NERDTree?) In order for this to work, one had to install patched "Nerd-font" versions of whatever programming font one wanted to use. For example:
# Original font
$ brew install --cask font-fira-code
# Patched variant
$ brew install --cask font-fira-code-nerd-fontPatching fonts with icons still works fine of course, and is, I think, pretty widely used. However, during my exploration of kitty, I discovered that there is a different (better?) approach to icon fonts. It turns out, you don't need a patched version of your chosen mono-spaced font. You can get most if not all the icons you need and use them alongside any font by just installing the Symbols Nerd Font Mono font.
Leveraging this approach depends on your terminal. In iTerm2, for example, you need to check "Use a different font for non-ASCII text" in the Preferences panel. Then select Symbols Nerd Font Mono font under "Non-ASCII font". (see screenshot below)
kitty does things a little differently. If you install a patched font, it will mostly work. Mostly. But the "kitty way" can be broken down in three steps:
- Install a normal, un-patched mono-spaced font, such as
Cascadia Code - Install a dedicated icon font, such as
Symbols Nerd Font Mono - Create a set of Unicode symbol maps1 to tell kitty which font to use for which icons (symbols)
More work up front, maybe, but less guesswork in the long-term once you understand what's going on. And if you're using my dotfiles, you have it easy. All the fonts you need are installed in Brewfile, and I have a set of Unicode symbol maps ready to go. 😎
Note
To learn more about Nerd fonts in terminals, as well as Unicode symbol maps and all the rest, be sure to check out Effective Nerd Fonts in Multiple Terminals by Elijah Manor
If you want to check whether icons and ligatures are working properly, try running the included nerd-font-smoke-test.sh script from the root of the dotfiles folder like so:
bash nerd-font-smoke-test.shIf your terminal is configured correctly, the output of the test should look like this:
Again, thank you, Elijah Manor!
Once upon a time, I almost left Vim due to some crippling performance issues. These issues were particularly painful when editing Ruby files. I documented what I learned here:
▹ What I've learned about slow performance in Vim
The .zshrc script can be profiled by touching the file ~/.zshrc.profiler and starting a new login shell. To see the top 20 lines that are taking the most time use the zshrc_profiler_view. zshrc_profiler parameters are number of lines to show (20) and path to profiler log file ($TMPDIR/zshrc_profiler.${PID}log).
- https://github.com/LazyVim/lazyvim
- https://github.com/LunarVim/LunarVim
- https://github.com/NvChad/NvChad
- https://github.com/LunarVim/Launch.nvim
- https://github.com/folke/dot
- https://github.com/nvim-lua/kickstart.nvim
- https://github.com/ThePrimeagen/init.lua
- https://github.com/elijahmanor/dotfiles
- https://github.com/cpow/cpow-dotfiles
- https://github.com/josean-dev/dev-environment-files
- https://github.com/glepnir/nvim
- https://github.com/numToStr/dotfiles
- https://github.com/jdhao/nvim-config
- https://github.com/brainfucksec/neovim-lua
- https://github.com/disrupted/dotfiles
- https://github.com/topics/neovim-dotfiles
- https://github.com/topics/neovim-config
- Pro Vim (https://github.com/Integralist/ProVim)
- Trevor Brown (https://github.com/Stratus3D/dotfiles)
- Chris Toomey (https://github.com/christoomey/dotfiles)
- thoughtbot (https://github.com/thoughtbot/dotfiles)
- Lars Kappert (https://github.com/webpro/dotfiles)
- Ryan Bates (https://github.com/ryanb/dotfiles)
- Ben Orenstein (https://github.com/r00k/dotfiles)
- Joshua Clayton (https://github.com/joshuaclayton/dotfiles)
- Drew Neil (https://github.com/nelstrom/dotfiles)
- Kevin Suttle (https://github.com/kevinSuttle/OSXDefaults)
- Carlos Becker (https://github.com/caarlos0/dotfiles)
- Zach Holman (https://github.com/holman/dotfiles/)
- Mathias Bynens (https://github.com/mathiasbynens/dotfiles/)
- Paul Irish (https://github.com/paulirish/dotfiles)
- http://dotfiles.github.io/
- https://medium.com/@webprolific/getting-started-with-dotfiles-43c3602fd789
- http://code.tutsplus.com/tutorials/setting-up-a-mac-dev-machine-from-zero-to-hero-with-dotfiles--net-35449
- https://github.com/webpro/awesome-dotfiles
- http://blog.smalleycreative.com/tutorials/using-git-and-github-to-manage-your-dotfiles/
- http://carlosbecker.com/posts/first-steps-with-mac-os-x-as-a-developer/
- https://mattstauffer.co/blog/setting-up-a-new-os-x-development-machine-part-1-core-files-and-custom-shell
Local customizations should be placed in *.local files:
~/.gitconfig.local- Personal git configuration~/.laptop.local- Additional laptop setup customizations
Copyright © 2014–2026 Joshua Steele. MIT License
