My macOS setup, written down as code.
One repo, a few commands, and a fresh Mac looks exactly like my last one.
What's inside · Prerequisites · Getting started · Day to day · Gotchas · Layout
This repo configures a whole Mac declaratively with nix-darwin and home-manager: system settings, apps, CLI tools, shell, editor, terminal, and AI agent configs.
It's public so you can read it, steal ideas, or fork it.
Note
This is a personal config, not a framework. Feature requests and pull requests aren't accepted (only collaborators can open PRs). If you find a real bug, open an issue using the bug report template.
| Area | What you get |
|---|---|
| macOS | Dark mode, fast key repeat, Dock, Finder, and trackpad preferences |
| Homebrew | GUI apps (casks) and CLI tools (brews), declared in configuration.nix |
| Nix packages | ripgrep, fd, fzf, jq, lazygit, Neovim, Hack Nerd Font |
| Shell | zsh, aliases, starship prompt |
| Editor | Neovim + lazy.nvim, rose-pine moon theme |
| Terminal | WezTerm, rose-pine moon theme, dimmed unfocused panes |
| AI agents | Claude, Codex, and opencode all share one AGENTS.md |
| AXI tools | gh-axi, chrome-devtools-axi, tasks-axi, quota-axi, lavish-axi installed globally with pnpm on rebuild; Claude Code hooks for gh-axi, chrome-devtools-axi and lavish-axi in home/.claude/settings.json |
| .NET | .NET 10 SDK via Nix, DOTNET_ROOT set, global tools (~/.dotnet/tools) on PATH |
Before you start, make sure you have:
- An Intel Mac, which is what this config targets. Apple Silicon (M1 or newer) works too with a one-line
hostPlatformchange, see step 4. On Apple Silicon you can also uncomment theherdrbrew inconfiguration.nix. - An admin account. The first switch changes system settings and needs
sudo. - Internet access. Nix, Homebrew, and Neovim plugins are all downloaded on first run.
- Xcode Command Line Tools, step 1 covers this.
- ~30 minutes. The first build downloads a lot. Later rebuilds take seconds. You do not need to install Homebrew yourself. nix-darwin manages it.
Install Apple's developer tools:
xcode-select --installClick through the dialog and wait for it to finish.
This config is built around Determinate Nix:
curl -fsSL https://install.determinate.systems/nix | sh -s -- installWhen it's done, close your terminal and open a new one so nix is on your PATH. Check it worked:
nix --versiongit clone https://github.com/Whatsaaaa/dotfiles.git
cd dotfilesSkip this step only if you're me. Otherwise, open these files and adjust:
| What | Where | Change it to |
|---|---|---|
| Username | user = "..." and home-manager.users.whatsaaaa in flake.nix, plus home.username and home.homeDirectory in home.nix |
your macOS username (run whoami); home.homeDirectory becomes /Users/<username> |
| Host label | darwinConfigurations."whatsaaaa-mac" in flake.nix and HOST="whatsaaaa-mac" in rebuild.sh |
any name, as long as both match |
| CPU | nixpkgs.hostPlatform in configuration.nix |
"aarch64-darwin" on Apple Silicon, "x86_64-darwin" on Intel |
configuration.nix derives its paths from user, but home.nix and the home-manager.users line in flake.nix don't read it, so change all four username spots together.
Warning
Every switch uninstalls any Homebrew package or app that isn't listed in configuration.nix. If you already use Homebrew, add everything you want to keep to brews and casks before continuing. See Gotchas.
home.nix finds config files through ~/.dotfiles, so this link must exist before the first build:
ln -s "$PWD" ~/.dotfilesMake sure everything evaluates before you let it touch your system:
nix flake check --no-build
nix build .#darwinConfigurations.whatsaaaa-mac.system --dry-runUse your own host label instead of whatsaaaa-mac if you changed it.
darwin-rebuild isn't installed yet, so run it straight from nix-darwin:
sudo nix run nix-darwin/nix-darwin-26.05#darwin-rebuild -- switch --flake .#whatsaaaa-mac- Open a new terminal. Your new shell, prompt, and
darwin-rebuildare only picked up by new sessions. - Log out and back in. Some macOS settings (like key repeat) only apply after that.
- Set your git identity, which this config deliberately doesn't do:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"- Launch
nvimonce while online, so it can install its plugins. You're done.
Change something, then apply it:
./rebuild.shWhether you even need that depends on what you changed:
| You changed... | Do you need ./rebuild.sh? |
|---|---|
A file under home/ (Neovim, WezTerm, AGENTS.md...) |
No. It's symlinked, so it's live immediately |
| A package, Homebrew app, alias, or macOS default | Yes |
| Added a brand new file anywhere | Yes, and git add it first (see below) |
Things that aren't obvious until they bite you.
configuration.nix sets homebrew.onActivation.cleanup = "zap". On every switch, Homebrew removes any formula or cask not in brews / casks, along with its data. Installing something with brew install by hand works only until your next rebuild. Add it to the list instead.
Flakes only see files tracked by git. If you create a new file and the build says it can't find it, run git add <file> (no need to commit) and rebuild.
~/.dotfiles points at wherever you cloned the repo, and all your config symlinks go through it. Move the folder and your editor, terminal, and shell configs all break at once. If you do move it, recreate the link:
ln -sfn /new/path/to/dotfiles ~/.dotfilesIf you already have files like ~/.zshrc or ~/.config/nvim, home-manager refuses to overwrite them and the switch fails with a "would be clobbered" error. Move them somewhere safe (or delete them) and run the switch again.
flake.nix and rebuild.sh both reference whatsaaaa-mac. If they disagree, the build fails with an error saying the configuration doesn't exist. Rename both together.
home/AGENTS.md is my personal policy, and it gets installed for Claude, Codex, and opencode. If you fork this, edit or delete it, or every agent you run will follow my rules without you noticing.
| Alias | Runs |
|---|---|
cc |
claude --dangerously-skip-permissions |
co |
codex --full-auto |
They let the agent run commands without asking. Convenient, but know what you're typing.
The config assumes Nix itself is installed and managed by the Determinate installer. If you used a different installer, you may get conflicts over who manages the Nix daemon.
The first nvim launch clones every plugin from GitHub. Offline, it starts with errors. After that first run, it works offline.
.
├── flake.nix # entry point: inputs, user, and the "whatsaaaa-mac" host
├── configuration.nix # system level: macOS defaults, Homebrew
├── home.nix # user level: shell, packages, prompt, symlinks
├── rebuild.sh # re-apply the config after a change
└── home/ # real config files, symlinked into ~
The files in home/ are your live config, not copies. home.nix uses mkOutOfStoreSymlink to point paths like ~/.config/nvim directly at home/.config/nvim in this repo, so the repo and your machine can never drift apart.
Neovim and WezTerm both use rose-pine moon. Neovim has italics off and a transparent background on macOS, Windows, and WSL, so it blends into the terminal.
MIT.