nicksp/dotfiles: A macOS Zsh and Homebrew Setup Built Around Symlinks
My personal dotfiles: Zsh, Git, VSCode, Obsidian, Ghostty, cmux, etc.
At a glance
- What is it?
- This is one person's macOS configuration repository, not a framework. It installs Zsh, Homebrew, CLI tools and app configs as symlinks into the home directory, and its README tells you to fork it rather than adopt it.
- Who is it for?
- Fork this repository if you run macOS with Zsh and Homebrew and want a working reference for symlink-based setup plus local override files such as ~/.zsh.local and ~/.gitconfig.local. Do not adopt it directly if you are on Linux, if you object to a setup.sh that runs unattended, or if you need the maintainer to respond to issues: the README asks for bug-fix pull requests only and states no support commitment.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 98 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not configuration, it is reproducibility on a new Mac
The repository addresses a narrow problem: bringing a fresh macOS install back to a known state. The README lists the requirements as macOS, Homebrew and Zsh, and notes that the install script will install the latter two. Everything else (shell aliases, Git aliases, a Starship prompt theme, VSCode settings, Firefox styles, Obsidian configuration, macOS defaults) lives in the repository and is linked into the home directory. The audience is one person, and the README says so twice: it recommends forking the repository to create your own set of dotfiles, and asks that pull requests only fix bugs or add improvements without breaking changes. Read that as a boundary rather than modesty. This is a working configuration that happens to be public, and the contribution policy is designed to keep it from drifting away from its owner's machine.
Symlinks out, local overrides in
The mechanism is symlinking. The README states that setup installs the dotfiles in your home directory as symlinks, and that everything is then configured by modifying files in ~/dotfiles. So ~/.gitconfig, ~/.zshrc and the rest point back into the clone, and an edit in either location is the same edit. Three escape hatches exist for machine-specific or secret values. If ~/.zsh.local exists it is sourced after all other shell files, so it can add to or overwrite aliases, settings and PATH. If ~/.ssh/config.local exists it is included after the public SSH hosts. If ~/.gitconfig.local exists it is included after the configurations from ~/.gitconfig. The README suggests using ~/.gitconfig.local for sensitive values such as Git user credentials for individual repositories. That layering is the part worth copying even if you ignore the rest: the public repository stays shareable while the private bits sit outside it.
Two install paths, and only one of them is inspectable at a glance
The manual path is explicit. Clone into ~/dotfiles, then run ./setup/zsh.sh, ./setup/brew.sh, ./setup/misc.sh and ./setup/symlinks.sh in that order. Four scripts, four visible steps, and you can read each one before running it. The automatic path is a single command: clone, then run ~/dotfiles/setup.sh. The README marks it with a caution and the words use at your own risk. That warning is doing real work. A single entry point that chains the other scripts is convenient on a new machine and opaque on a machine you care about, because you cannot see from the invocation which of the four stages will run or in what order. If you are evaluating this repository, start with the manual sequence. The README also front-loads prerequisites that the scripts do not handle: pointing DNS at Cloudflare (1.1.1.1 and 1.0.0.1, plus the two IPv6 addresses), generating an SSH key and adding it to the ssh-agent, registering the public key with GitHub, testing with ssh -T git@github.com, and configuring GPG commit signature verification. It also asks you to install the MonoLisa font, which is a commercial product. None of that is bundled.
What the repository actually contains
The README's inventory is the most useful part of the documentation, and it is uneven in detail. Named items include a custom color scheme called Squirrelsong under colors/, CLI scripts under bin/, coding agent config automation under agents/, a Starship theme at tilde/.starship.toml with Git status, Git aliases in tilde/.gitconfig, Zsh aliases in zsh/aliases.zsh, an Obsidian setup described as a second brain, fzf integration in zsh/fzf.zsh, hunk as a terminal diff viewer, macOS defaults in setup/macos.sh, Visual Studio Code settings synchronization under vscode/, Firefox custom styles, and a Brewfile at setup/Brewfile listing macOS apps and VSCode extensions. The topics list adds agentic-ai-development, ai-agents, amp, cmux, Ghostty, lazygit, lazydocker and starship-prompt. Two extras are exposed as commands. Running set-defaults applies the macOS defaults. Running sync-color-themes installs the color themes. Alternative app icons are documented separately in icons/README.md. What the README does not give is any explanation of how the agents/ directory is wired into the shell, or what cmux does. Those are the least documented and, given the repository's topic tags, apparently the most actively developed parts.
Updating is a pull and a re-run, which is also the failure mode
Updating means cd ~/dotfiles, git pull, then ./setup.sh. That re-runs the full setup rather than a diff, so a pull can change more than the files you edited. The README's request for non-breaking pull requests is an attempt to keep that re-run safe, but it is a convention, not a guarantee. There are no releases in the retrieved material, so there is no version to pin and no changelog to read before pulling. The practical consequence: if you fork and then track upstream, you are re-running an install script whose contents changed without your review. If you fork and stop tracking upstream, you own the maintenance, which for a repository of this breadth means periodically revisiting the Brewfile and the macOS defaults as tools change. Neither path is wrong, but the second one is the one the README implicitly assumes. The licence is MIT, which permits reuse, modification and redistribution provided the copyright notice and permission notice are preserved. That is the whole of what the repository states about licensing; it says nothing about the third-party configurations it vendors, such as Firefox styles or VSCode settings, and nothing about the commercial MonoLisa font, which is not covered by the MIT grant.
Where a general-purpose tool would be the better choice
The structural alternative is a dotfiles manager such as GNU Stow, chezmoi or yadm, rather than a personal repository. The difference is in what each one knows. This repository's setup/symlinks.sh is a script written for one directory layout on one operating system; it links a fixed set of paths and assumes macOS. A manager like chezmoi, by contrast, models the home directory as a source tree with templating and per-machine variation, so the same repository can produce different files on a work laptop and a personal one without a .local override convention. Stow takes a lighter approach, treating each top-level directory as a package and symlinking it wholesale, which gives you selective installation without a custom script. If your requirement is one machine and you want to read every step, the scripts here are simpler than learning a manager's model. If your requirement is several machines with genuinely different configurations, the .local file convention will run out of room, because it handles overrides but not structural divergence. The honest comparison is that this repository is a configuration, and a manager is a mechanism for producing configurations. They solve different problems, and the README's fork recommendation points at the first.
Who should take this, and what to check before running anything
Take it if you are setting up macOS with Zsh and Homebrew and want a concrete, readable reference for symlink installation with local override files. The three .local hooks are the transferable idea, and the manual four-script path is easy to audit. Skip it if you run Linux, if you want a maintained product with issue triage and releases, or if you are uncomfortable running setup.sh without reading the scripts it invokes. Before running anything, read setup/Brewfile to see the full application list, read setup/macos.sh to see which system defaults will change, and confirm whether the MonoLisa font and the Cloudflare DNS change are acceptable on your machine. Then run the manual sequence rather than setup.sh, so each stage is a decision you made rather than a step you delegated. The repository will still be there after you have read the four scripts, and that reading is the only thing standing between a fork and an unattended install.
Editorial conclusion
Fork this repository if you run macOS with Zsh and Homebrew and want a working reference for symlink-based setup plus local override files such as ~/.zsh.local and ~/.gitconfig.local. Do not adopt it directly if you are on Linux, if you object to a setup.sh that runs unattended, or if you need the maintainer to respond to issues: the README asks for bug-fix pull requests only and states no support commitment. Verify first that ./setup/zsh.sh, ./setup/brew.sh, ./setup/misc.sh and ./setup/symlinks.sh do what you expect on your machine, and check setup/Brewfile for the full list of apps it will install. The MonoLisa font and the Cloudflare DNS step are prerequisites you supply yourself.
Community notes