nicknisi/dotfiles: a personal macOS setup driven by Mise bootstrap

Who nicknisi/dotfiles is actually for

The README is explicit that these are working dotfiles, not a starter kit. That single sentence sets the audience. This is a repository to read, borrow from, or fork for one specific machine shape: an Apple Silicon Mac, Homebrew under /opt/homebrew, a checkout at ~/Developer/dotfiles, and several sibling repositories under ~/Developer. If your machine does not match that shape, you are editing someone else's setup rather than installing your own.

The value is in the choices, not the packaging. The README's table names the current stack: Ghostty as the terminal (with WezTerm and Kitty configs still tracked), Homebrew zsh and Starship, tmux, Neovim with lazy.nvim, AeroSpace with SketchyBar, Borders and Karabiner-Elements for window management, Monaspace and Symbols Nerd Font for type, and Tokyo Night for color. The CLI agent entries (Pi and Claude Code) and the agent orchestration tool (Fleet) are the most personal layer, and they are the first thing a fork should delete.

There is also a time-capsule note. The README points to a commit from a vim and tmux talk and warns that the current setup is substantially different. If you found this repository through that talk, the branch you want is not main.

How the Mise bootstrap turns a manifest into a machine

The mechanism is a single manifest, config/mise/config.toml, executed by mise bootstrap. The README lists the order: on macOS a pre-packages hook installs Homebrew, applications and fonts; OS-specific packages come from [bootstrap.packages] through Homebrew or apt; repositories from [bootstrap.repos] are cloned; the [dotfiles] symlinks are applied; macOS defaults are set and the login shell changed; runtimes and CLI tools from [tools] are installed; and finally the bootstrap task registers the repository's Git clean filter for pi-settings.

Linking is the part worth understanding before you fork. Mise links directories rather than copying individual files, and the two declarations are deliberately broad:

[dotfiles]
"~/.config/*" = "~/Developer/dotfiles/config/*"
"~/.??*" = "~/Developer/dotfiles/home/.??*"

That second pattern catches dotfiles in the home directory, which is how home/.claude, home/.pi and home/.zshenv land in place. Because the source path is fixed at ~/Developer/dotfiles, the clone location is not a preference. Change it and you edit the manifest.

The devcontainer is the interesting counterweight. It runs the same bootstrap in Ubuntu, which means the portable terminal configuration can be exercised without touching the host. The README notes one caveat there: on Linux ARM, the diffdad, fleet, tm and sessions tools are skipped until their releases include ARM assets.

Installing nicknisi/dotfiles on a Mac

The documented install is a single curl command. The installer checks for Git, clones the repository, installs Mise and runs one full bootstrap:

curl -fsSL https://raw.githubusercontent.com/nicknisi/dotfiles/main/install.sh | bash

On a Mac without the Xcode Command Line Tools, the first run opens Apple's installer and stops. Run the same command again after those tools finish. That two-pass behaviour is documented, not a bug you need to debug.

Because this script rewrites your home directory, preview it first. The README gives a dry run and a plain-output switch:

curl -fsSL https://raw.githubusercontent.com/nicknisi/dotfiles/main/install.sh | bash -s -- --dry-run

Set NO_COLOR=1 for plain output. After a real install, open a new login shell and write the machine-local Git identity, which the task stores in ~/.gitconfig-local, a file included by the tracked config but never committed:

mise run setup-git

The manual path is also documented, and it makes the moving parts visible. It needs the Xcode tools, a clone at the expected path, Mise installed, and an explicit MISE_GLOBAL_CONFIG_FILE before bootstrap has created ~/.config/mise:

xcode-select --install # only when Git is missing
git clone https://github.com/nicknisi/dotfiles.git ~/Developer/dotfiles
curl -fsSL https://mise.run | sh
export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"

MISE_GLOBAL_CONFIG_FILE=~/Developer/dotfiles/config/mise/config.toml \
  mise bootstrap --yes

Two prerequisites are stated plainly: Apple Silicon Homebrew paths under /opt/homebrew, and a working GitHub SSH key, because [bootstrap.repos] clones ~/Developer/pi-extensions, ~/Developer/ideation and ~/Developer/claude-plugins over SSH. Without that key the bootstrap cannot complete its repository step.

Managing the symlinks after the first run

Once the machine is bootstrapped, the dotfile links are the thing you will actually operate. The README documents a status check, an apply, a scoped apply, and the matching unapply commands:

mise bootstrap dotfiles status
mise bootstrap dotfiles apply --yes
mise bootstrap dotfiles apply --yes ~/.config/nvim
mise bootstrap dotfiles unapply --yes
mise bootstrap dotfiles unapply --yes ~/.config/nvim

The rule to remember is that you unapply a target before deleting or renaming its source. Mise refuses to overwrite a real file with a symlink unless you pass --force, which is the right default for a tool that writes into ~/.config. If you have an existing ~/.config/nvim, the first apply will not silently eat it.

Dangling links from earlier experiments are found with find, and the README is careful to say these commands only print candidates:

find ~/.config -type l ! -exec test -e {} \; -print
find ~ -maxdepth 1 -type l ! -exec test -e {} \; -print

Check each target before removing anything. The broad ~/.??* glob means a stale link can sit directly in your home directory, not only under ~/.config, so both commands matter.

The hardcoded path is the main limitation

The fixed source path is the first real constraint, and the README says so: the repository must live at ~/Developer/dotfiles unless you edit the manifest. That is not a configuration detail you can paper over with a symlink, because the [dotfiles] declarations point at the literal path.

The second constraint is the private repositories. Bootstrap clones three of them over SSH, so a machine without the matching GitHub key fails at step three of seven. You can edit [bootstrap.repos], but then you are maintaining a fork rather than using this one.

The third is platform. The README states that the host setup assumes Apple Silicon macOS and that the devcontainer exists to check the portable terminal configuration in Ubuntu. Linux is not a supported host here. The related searches around Hyprland, Niri, Arch and KDE have no counterpart in this repository: there is no Wayland compositor config, no stow, and no distro package list beyond what apt installs inside the devcontainer.

Finally, the personal layer is dense. Pi, Claude Code, Fleet, the 1Password CLI, Wrangler, Greptile and the WorkOS CLI are all in [tools]. Each one is an account, a login or a licence you may not have. The README does not document rollback for a partial bootstrap, so the practical recovery path is the unapply commands and manual inspection of dangling links.

How this differs from stow or a generic dotfiles manager

GNU Stow is the usual alternative, and the difference is in what drives the operation. Stow is a symlink farm manager: you keep packages in directories and run stow to create links, and the mapping is implied by the directory tree. There is no manifest, no package installation and no OS setup. It is portable across Linux and macOS because it does nothing but link.

Mise bootstrap here is a machine provisioner that happens to include linking. The manifest declares packages, repositories, tools, macOS defaults and the login shell alongside the [dotfiles] symlink rules, and it runs them in a fixed order. That is why the install can start from a bare Mac and end with a configured shell, and it is also why the repository is tied to Homebrew paths, a clone location and SSH access. If you only want your Neovim and zsh configs linked on three different machines, Stow does the job with far less surface area. If you want one command to rebuild a Mac, the Mise manifest is the closer fit, at the cost of the constraints above.

A second comparison is the devcontainer. Rather than trying to make the host setup portable, the repository runs the same bootstrap in Ubuntu inside Docker. That is a different answer to the same problem: instead of abstracting the platform, it reproduces the setup in a container and tests the terminal configuration there.

Maintenance, updates and what the MIT licence does not cover

The repository is not archived, and the README does not state a last push date, so there is no basis for calling it actively maintained. Treat it as a snapshot of one person's machine. The update surface is documented though, and it is broad: mise run update refreshes Neovim plugins, Homebrew, zsh plugins, Mise tools, uv tools, Pi extensions and the repository itself. That is the upgrade cost in one command, and it is also the risk, because a single task touches every layer at once.

There is a second upgrade path worth knowing about. The README links an older commit from a vim and tmux talk and says the current setup is substantially different. If you forked from that commit, pulling main is a migration, not an update.

The licence is MIT, which is permissive and places few conditions on reuse or modification. That covers the code and configuration in the repository. It does not cover the third-party applications, fonts or commercial CLI tools the manifest installs, and it does not cover the three private repositories cloned over SSH, which have their own terms. The MIT file in the repository root is the only licence statement here; nothing in the README addresses redistribution of the bundled themes or the tracked WezTerm and Kitty configs.

Editorial conclusion

Adopt nicknisi/dotfiles only if you are on Apple Silicon macOS, willing to keep the checkout at ~/Developer/dotfiles, and ready to prune the personal parts: the Pi and Fleet tooling, the Claude Code and 1Password CLI entries, the AeroSpace and SketchyBar window management, and the three private repositories cloned over SSH. If you want a portable base for Linux or a shared team configuration, start elsewhere, because the manifest hardcodes Homebrew paths, clone destinations and GitHub SSH access. Before running anything, read config/mise/config.toml and check whether [bootstrap.repos] can reach your SSH keys; if it cannot, the bootstrap stops partway through and you are left with a half-linked home directory. The dry run is the cheapest way to see the full plan first.

Frequently asked questions

Official sources

1. Official README
2. Project repository