dotfiles

Watch the walkthrough: https://youtu.be/5N-okeDdIuI

My personal Mac setup, managed with nix-darwin and home-manager. One repo, one command, and a fresh Mac ends up configured the same way every time.

Contributing / Using This Repo

These are my personal dotfiles, shared publicly so people can read them, learn from them, and fork them freely. Feature requests and pull requests are not accepted here, and PRs are auto-closed. If you find a bug, please open a GitHub Issue using the bug report template.

What you get

Running the switch builds:

• System settings (dark mode, key repeat, dock, Finder, trackpad)
• Homebrew apps (casks and CLI tools)
• Nix user packages (ripgrep, fd, fzf, jq, lazygit, Neovim, Hack Nerd Font)
• Shell (zsh, aliases, starship prompt)
• Editor (Neovim config)
• Terminal (WezTerm config)
• Agent configs (Claude, Codex, opencode all share one AGENTS.md)

Prerequisites

• Apple Silicon Mac, by default.
• Intel Mac: change one line. In configuration.nix, set nixpkgs.hostPlatform = "x86_64-darwin"; (the comment right there tells you the same thing).

Fresh-machine setup

On a brand new Mac, from a bare clone of this repo:

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

Before you run it: review "Make it yours" below. Change the host label or CPU architecture if needed, and read the Homebrew cleanup warning. bootstrap.sh applies the config to your machine, so do this first.

./bootstrap.sh

bootstrap.sh does four things, in order:

1. Installs Determinate Nix, if it isn't already installed.
2. Symlinks this repo to ~/.dotfiles. This has to happen before the first build, because home.nix points at config files through ~/.dotfiles.
3. Checks the user configured in flake.nix against your actual macOS username, and offers to fix it for you if they differ.
4. Runs the first darwin-rebuild switch. It fetches the darwin-rebuild tool from the nix-darwin 26.05 release branch, then applies this repo's locked flake config.

After that, darwin-rebuild exists and you're on the normal workflow below.

Validate without applying

Once Nix is installed (bootstrap.sh step 1 handles that), you can check that the config builds without touching your system - handy when you have edited something:

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

If you renamed the host label in "Make it yours", substitute your label for mac in these commands.

Daily use

Edit the config files in place, then apply:

./rebuild.sh

That's it. No separate build-and-copy step.

Make it yours

This repo is mine. If you clone it, review these before you run bootstrap.sh:

• Username: run ./bootstrap.sh (it detects your macOS username and offers to set it) OR change the single user = "kunchen" line in flake.nix. Everything else (configuration.nix, home.nix, home directory paths) is threaded from that one variable.
• Host label "mac", in three places: flake.nix (the darwinConfigurations."mac" name), rebuild.sh:5 (the #mac at the end of the flake reference), and bootstrap.sh's first-switch command (also #mac). All three have to match.
• CPU architecture, hostPlatform in configuration.nix (see Prerequisites above).

Git identity: this config deliberately does not set your git name or email. Git will stop your first commit and tell you to set them (git config --global user.name "Your Name" and git config --global user.email you@example.com). If you'd rather manage that declaratively, add this back to home.nix with your own identity:

programs.git = {
  enable = true;
  settings.user = {
    name = "Your Name";
    email = "you@example.com";
  };
};

Homebrew cleanup warning: configuration.nix sets homebrew.onActivation.cleanup = "zap". That means every time you switch, Homebrew removes any package or cask on your machine that isn't listed in the brews and casks arrays in configuration.nix. If you already have Homebrew stuff installed that isn't in that list, the first switch will uninstall it. Read through brews and casks before you run bootstrap.sh or rebuild.sh for the first time, and add anything you want to keep.

About herdr: it's in the brews list. It's a real public Homebrew formula (brew info herdr finds it in homebrew-core, no tap needed), so it will install fine. If you don't use it, just remove it from brews in your copy.

Heads-up:

• home/AGENTS.md is my personal agent policy, and home.nix installs it for Claude, Codex, and opencode. If you clone this repo, you'd silently inherit my agent instructions - edit or delete home/AGENTS.md if you don't want that.
• The cc and co shell aliases in home.nix are high-agency shortcuts: claude --dangerously-skip-permissions and codex --full-auto. They're convenient for me, but know what they do before you use them.

Repo tour

• flake.nix - the entry point. Wires up nixpkgs, nix-darwin, home-manager, and nix-homebrew, and declares the mac machine.
• configuration.nix - system-level config: macOS defaults, Homebrew.
• home.nix - user-level config: shell, packages, prompt, and the symlinks described below.
• rebuild.sh - re-applies the config after the first switch. Run this every time you make a change.
• home/ - the actual config files that get symlinked into place (Neovim, WezTerm, herdr, Claude settings, the shared AGENTS.md).

How the symlinks work

The files under home/ are the real files - editing them here is editing your live config, no rebuild needed to see the change in your editor. home.nix uses mkOutOfStoreSymlink to point paths like ~/.config/nvim straight at home/.config/nvim in this repo, so the two never drift out of sync. You only run ./rebuild.sh when you change something that isn't just a symlinked file, like a package list or a system default.

Notes

The first time you launch nvim, it bootstraps lazy.nvim by cloning plugins from GitHub. That needs network access once; after that it's offline.

License

This repo is licensed under MIT No Attribution. See LICENSE.