Nix Configuration Assistant
Expert assistant for managing NixOS/nix-darwin configurations with flakes, home-manager, and multi-architecture support.
Overview
This skill helps you work with a comprehensive nix-darwin + home-manager configuration that supports:
Multi-architecture systems (Apple Silicon with x86_64 fallbacks)Cross-platform configurations (macOS and Linux)Multiple nixpkgs versions via overlaysHomebrew integration for macOSDevelopment environment managementKey Commands
Build & Deploy
**Test changes**: `darwin-rebuild build --flake .` (alias: `drb`)**Apply configuration**: `darwin-rebuild switch --flake .` (alias: `drs`)**Update inputs**: `nix flake update` (alias: `flakeup`)**Important**: Always use expanded commands (not aliases) when running via the Bash tool, as Claude Code may not have access to fish shell aliases.
When to Prompt User
Before running `darwin-rebuild switch` (ask user to run it)Before running `nix flake update` (ask user to run it)After successfully building with `darwin-rebuild build`, suggest user can apply with `drs`Configuration Structure
Flake Inputs
`nixpkgs-master`: Latest from master branch`nixpkgs-stable`: Stable release (24.11-darwin)`nixpkgs-unstable`: Primary package source`nixos-stable`: Stable NixOS (24.11)`darwin`: nix-darwin for macOS`home-manager`: User environment management`prefmanager`: macOS preferences toolSystem Configurations
`notnux6`: Primary macOS configuration (Apple Silicon)`bootstrap-x86/bootstrap-arm`: Minimal bootstrap configs`githubCI`: CI-specific configuration`homeConfigurations.matt`: Linux VM configurationDirectory Structure
`darwin/`: macOS system configuration modules`home/`: home-manager user configuration modules`modules/`: Shared modules for both darwin and home-manager`overlays/`: Custom nixpkgs overlays`pkgs/`: Custom package definitionsKey Files
`darwin/defaults.nix`: macOS system defaults`darwin/general.nix`: System packages and environment`darwin/homebrew.nix`: Homebrew integration`home/fish.nix`: Fish shell configuration with aliases`flake.nix`: Main flake configurationCode Style Guidelines
Formatting
Use 2-space indentationKeep lines under 100 charactersAdd spaces around operators and after parameter blocksUse empty lines between logical sectionsStructure
Import order: stdlib (lib, pkgs, config), external modules, local modulesUse standard function pattern: `{ config, pkgs, lib, ... }: { ... }`Use `let ... in ...` for local definitionsAdd vim fold markers `{{{` and `}}}` with descriptive section headersNaming
camelCase for variables and functionskebab-case for module and file namesBest Practices
Use `?` for optional parametersUse `lib.optional` for conditional listsPrefer `mkIf` for conditional optionsKeep error handling explicit with proper checksWorking with This Configuration
Multi-Architecture Support
Primary architecture: Apple Silicon (aarch64-darwin)Automatic x86_64 package fallbacks for incompatible packagesCross-platform home-manager for Linux VMsPackage Management
Multiple nixpkgs versions available: `pkgs-master`, `pkgs-stable`, `pkgs-unstable`Custom node packages via `node2nix` in `pkgs/node-packages/`Homebrew casks and Mac App Store apps via `darwin/homebrew.nix`Registry Integration
The flake is registered as `my` in the nix registry:
`nix run my#<package>` - Run a package`nix shell my#<shell>` - Enter development shell`nix build my#<output>` - Build specific outputCritical Nix + Git Interaction
**IMPORTANT**: Nix flakes use git to determine what files exist.
**New files**: Must be staged with `git add` before nix will see them (even uncommitted)**Tracked files**: Changes are visible to nix immediately without stagingAlways `git add` new `.nix` files before running build commandsGeneral Principles
1. **Understand root causes**: Don't hack around problems with overlays. Seek to understand and fix issues at their source.
2. **Keep it simple**: Prefer straightforward solutions over complex workarounds.
3. **Test before applying**: Always `darwin-rebuild build` before suggesting `darwin-rebuild switch`.
4. **Respect git workflow**: Remember to stage new files before building.
Common Tasks
Adding a Package
1. Decide which nixpkgs version to use (unstable, stable, or master)
2. Add to appropriate module in `darwin/general.nix` or `home/` modules
3. Stage changes if new files: `git add <files>`
4. Test build: `darwin-rebuild build --flake .`
5. Ask user to apply: "Ready to apply with `drs`?"
Modifying System Defaults
1. Edit `darwin/defaults.nix`
2. Use proper option types and defaults
3. Test build before suggesting switch
Adding Home Manager Configuration
1. Edit or create module in `home/`
2. Import in main home-manager configuration
3. Stage new files with git if created
4. Test and suggest user applies changes
Debugging Build Failures
1. Check error messages for missing dependencies
2. Verify new files are staged with git
3. Check for syntax errors in Nix expressions
4. Consider architecture-specific issues (ARM vs x86)
5. Look for overlay conflicts or package version mismatches
Example Workflow
When user asks to add a new package:
1. Read relevant configuration files
2. Identify correct location for the package
3. Add package with proper syntax
4. If creating new files, remind user to `git add` them
5. Run `darwin-rebuild build --flake .` to test
6. If successful, inform user: "Build successful. You can apply changes with `darwin-rebuild switch --flake .` or the alias `drs`."
7. If build fails, analyze errors and iterate