kunchenguid/dotfiles: a nix-darwin Mac setup driven by one command

What kunchenguid/dotfiles actually solves

A new Mac normally means a day of reinstalling apps, retyping shell aliases, and hunting for the one Finder setting you always change. This repository compresses that into a clone, a review pass, and `./bootstrap.sh`. The README states the goal plainly: "One repo, one command, and a fresh Mac ends up configured the same way every time."

The audience is narrow and the README says so. These are the author's personal dotfiles, published so others can read and fork them. Feature requests and pull requests are not accepted, and PRs are auto-closed. Bug reports go through a GitHub issue template. So the realistic use is as a reference implementation for nix-darwin on macOS, or as a fork you own outright. If you want a project that will merge your patches, this is the wrong starting point, and that is a deliberate choice rather than an oversight.

The scope is macOS only. Prerequisites list an Apple Silicon Mac by default, with an Intel path that means editing one line in `configuration.nix`. There is no Linux or Windows story here, which matters because a large share of dotfiles repositories people search for are Linux desktop setups.

How the flake, the switch, and the symlinks fit together

The entry point is `flake.nix`, which wires up nixpkgs, nix-darwin, home-manager, and nix-homebrew, and declares a machine named `mac`. From there the split is clean: `configuration.nix` holds system-level settings such as macOS defaults and Homebrew, while `home.nix` holds the user-level shell, packages, prompt, and symlinks. `rebuild.sh` re-applies the config after the first switch.

The design decision worth studying is the symlink model. Files under `home/` are the real files. `home.nix` uses `mkOutOfStoreSymlink` to point paths such as `~/.config/nvim` straight at `home/.config/nvim` inside the repository. Editing the file in the repo is editing your live config, with no rebuild needed to see the change in your editor, and the two copies cannot drift apart. That is different from the common Nix pattern of copying files into the store, where every tweak requires a rebuild before it takes effect.

The consequence is that `./rebuild.sh` is only needed when you change something that is not just a symlinked file, such as a package list or a system default. It also means the repository has to live at `~/.dotfiles`, because `home.nix` resolves those paths through that location. Moving or renaming the checkout breaks the links.

Agent configuration is handled separately: `home.nix` installs one `AGENTS.md` for Claude, Codex, and opencode, so all three read the same policy file. Pi gets a narrower treatment. It is opt-in, not vendored, and Home Manager owns exactly two repository-authored Pi directories, `~/.pi/agent/themes` and local extensions, according to the README.

Installing it on a fresh Mac and running the first switch

Start with a bare clone. The README is explicit that you should review the "Make it yours" notes before running anything, because the first switch can remove software.

git clone https://github.com/kunchenguid/dotfiles.git
cd dotfiles

Before the first run, open `configuration.nix` and read the `brews` and `casks` arrays. The README warns that `homebrew.onActivation.cleanup = "zap"` makes Homebrew remove any package or cask on your machine that is not in those lists. Add anything you want to keep.

Then run the bootstrap script. The README describes four steps in order: install Determinate Nix if missing, symlink the repo to `~/.dotfiles`, check the `user` in `flake.nix` against your actual macOS username and offer to fix it, and run the first `darwin-rebuild switch`.

./bootstrap.sh

After that, `darwin-rebuild` exists and the daily workflow is a single command after you edit config files in place.

./rebuild.sh

If you renamed the host label, substitute your label for `mac` in the validation commands. You can check that a config builds without touching the system once Nix is installed.

nix flake check --no-build
nix build .#darwinConfigurations.mac.system --dry-run

One deliberate omission: the config does not set your git name or email. Git stops your first commit and asks for them. If you prefer to manage that declaratively, the README shows adding a `programs.git` block back into `home.nix` with `settings.user.name` and `settings.user.email`.

The Homebrew zap setting is the sharpest edge here

Declarative package management has a failure mode that imperative installs do not: the tool believes the declaration is the whole truth. With `homebrew.onActivation.cleanup = "zap"`, every switch reconciles your machine against the `brews` and `casks` arrays and removes what is not listed. On a machine that already has Homebrew packages, the first switch is a destructive operation, not an additive one.

The README handles this honestly by putting the warning before the setup instructions and telling you to read both arrays first. It is still the thing most likely to cost a new user an afternoon of reinstalling something they forgot they had. If you keep a work laptop with a long tail of Homebrew installs you do not fully remember, this repository is the wrong tool until you inventory them.

The other edge is the `cc` and `co` shell aliases in `home.nix`, which the README describes as high-agency shortcuts expanding to `claude --dangerously-skip-permissions` and `codex --full-auto`. Those flags are visible in the alias definitions, so nothing is hidden, but they remove confirmation prompts. The README's own framing is to know what they do before you use them.

Finally, `home/AGENTS.md` is the author's personal agent policy and `home.nix` installs it for Claude, Codex, and opencode. Clone this repo without editing that file and you silently inherit someone else's agent instructions. That is a real inherited-behaviour risk, and the README flags it rather than burying it.

How this differs from GNU Stow and from a Linux dotfiles repo

GNU Stow is the usual comparison point for people searching for a dotfiles manager. Stow is a symlink farm manager: you keep files in package directories and it creates links into your home directory, with no package installation and no system settings. This repository also ends up symlinking files into place, but the similarity stops there. The links are created by home-manager through `mkOutOfStoreSymlink` as part of a Nix evaluation, and the same evaluation also installs packages, applies macOS defaults, and manages Homebrew. Stow does not touch any of that, and it does not need Nix.

The trade-off runs both ways. Stow has a much smaller surface: no flake lock, no store, no rebuild step, and no package-removal behaviour to reason about. This repo gives you reproducibility across machines, which Stow cannot provide on its own, at the cost of a Nix dependency and a config that has to be read before it is run.

Against the Linux desktop repositories that dominate dotfiles search results, the split is architectural rather than stylistic. Those setups typically target a window manager and a shell on Arch or similar, and the related searches for Hyprland and Arch reflect that. This one targets macOS system settings, Homebrew casks, and Apple Silicon. The symlink and rebuild ideas transfer; the actual configuration files do not.

Maintenance, licence, and what forking costs you

The repository is not archived, and the last push was on 2026-08-27. It carries the MIT-0 licence, which is the MIT licence with the attribution requirement removed. In practice that means you can fork, modify, and redistribute this configuration without keeping a copyright notice, which is unusually permissive for a dotfiles repo and removes the awkward question of whether a config file needs a licence header. This is a description of the licence text, not legal advice; read LICENSE yourself if the distinction matters to you.

Maintenance cost sits with you, not upstream, and the README makes that structural rather than accidental. Pull requests are auto-closed, so any fix you need lives in your fork. The flake is locked, and `bootstrap.sh` fetches `darwin-rebuild` from the nix-darwin 26.05 release branch, which means the nix-darwin line is pinned by the bootstrap path. Upgrading nixpkgs or nix-darwin is a change you make and validate with `nix flake check --no-build` before applying.

The host label is the most fragile piece of the fork. The README says `"mac"` appears in three places: the `darwinConfigurations."mac"` name in `flake.nix`, the `#mac` at the end of the flake reference in `rebuild.sh` on line 5, and the first-switch command in `bootstrap.sh`. All three have to match. Rename one and forget the others and the switch fails with a reference to a configuration that does not exist. The `user` value is better threaded: everything else derives from that single line in `flake.nix`.

Editorial conclusion

Adopt this repo only as a fork base: read the brews and casks arrays in configuration.nix first, because homebrew.onActivation.cleanup = "zap" removes anything not listed on every switch. Skip it if you want a maintained upstream or a Linux desktop setup, since the config targets Apple Silicon and the author states that pull requests are auto-closed. Verify three things before running bootstrap.sh: the user value in flake.nix matches your macOS username, the host label "mac" appears in all three places the README names, and home/AGENTS.md is something you are willing to inherit.

Frequently asked questions

Official sources

1. Issues
2. kunchenguid/dotfiles on GitHub
3. License: MIT-0
4. README