nix-darwin

Configure this macOS dotfiles repository's Nix modules, hosts, and packages, or diagnose darwin-rebuild failures.

SKILL.md

GitHub

nix-darwin Configuration

Two hosts (workstation, homelab) are built by mkDarwinConfig in flake.nix from three layers: darwin modules (system) → home-manager (user) → nix-homebrew (GUI apps and taps). Both hosts share nixpkgs-unstable. Read the host's home.nix and homebrew.nix for what is currently enabled; do not rely on remembered program lists.

Conventions

New programs follow templates/program-module.md: an options.my.<program>.enable module under modules/home-manager/programs/, imported by the host's home.nix and enabled there. Shared programs are imported by modules/home-manager/base.nix instead.

Config delivery When to use Example
mkOutOfStoreSymlink Config edited often, applied without rebuild neovim, aerospace
builtins.readFile Config copied into the Nix store zed-editor
Inline Nix settings Small, Nix-native config ghostty, starship

Naming: kebab-case.nix files and host names, my.<program>.enable options, symlink/<name>.symlink dotfiles, and conventional commit scopes such as feat(neovim): or fix(darwin):.

Read by problem

Problem or decision Reference
Where a module is wired in, or why the layout is shaped this way architecture.md
Build, rollback, generations, input updates, garbage collection commands.md
darwin-rebuild or evaluation failure, Homebrew DSL or tap errors, macOS compatibility gotchas.md
The user asks how to restructure or improve the configuration community-patterns.md — check each pattern's status in this repo first

Complete the change

Evaluate each affected host with nix eval --raw .#darwinConfigurations.<host>.system.drvPath. nix flake check only checks formatting and passes even when a host fails to evaluate; nix fmt fixes formatting. Changes under modules/, hosts/, or flake.nix take effect only after darwin-rebuild switch; follow the project CLAUDE.md for when that needs confirmation.