nix-config/AGENTS.md

AGENTS.md

Overview

Nix flake managing 3 devices: Mac Mini, MacBook Air (both aarch64-darwin via nix-darwin), and a Windows PC via NixOS-WSL (x86_64-linux). Single user imbytecat everywhere.

Architecture

flake.nix
├── darwinConfigurations.mac-mini    (aarch64-darwin)
├── darwinConfigurations.macbook-air (aarch64-darwin)
└── nixosConfigurations.wsl          (x86_64-linux)

• lib/default.nix — builders: mkDarwin, mkNixos, mkHome
• modules/shared/ — both platforms (nixpkgs config, overlays, nix settings)
• modules/darwin/ — macOS: system preferences, homebrew (casks/brews/masApps), fonts
• modules/nixos/ — NixOS: base packages, docker, locale, user
• home/ — home-manager (shared across all hosts via useGlobalPkgs)
• overlays/ — custom packages (comment-checker)

Nix implementation

All platforms use Lix (nix.package = pkgs.lix in modules/shared/nix.nix). Lix is a community fork of CppNix — same CLI, different implementation (partial Rust rewrite, ~20-30% faster, better error messages).

• macOS installed via Lix installer
• nix.enable = true on all platforms — nix-darwin fully manages the Nix daemon, /etc/nix/nix.conf, and nix.settings
• nix.settings (flakes, warn-dirty) applies uniformly across all 3 devices

Critical gotchas

• catppuccin.nvim disabled: catppuccin.nvim.enable = false in home/theme.nix due to catppuccin.lib.detect_integrations require check failure in nixpkgs. Re-test periodically.
• catppuccin module name: Uses catppuccin.homeModules.catppuccin (not the old homeManagerModules).
• Homebrew tap casks: Casks from taps need full path in the casks list (e.g. "goooler/repo/fl-clash"), not just the short name.
• onActivation.cleanup = "zap": Any brew formula/cask NOT declared in modules/darwin/default.nix WILL be removed on rebuild. Be comprehensive.
• Repo location: The repo lives at ~/Developer/nix-config. Fish abbreviations (rebuild, update) reference this path.
• First-time bootstrap requires sudo: sudo nix run nix-darwin -- switch --flake .#mac-mini (not darwin-rebuild which doesn't exist yet).

Commands

# Validate (eval only, fast)
nix build .#darwinConfigurations.mac-mini.system --dry-run

# Validate (actual build, catches runtime failures like require checks)
nix build .#darwinConfigurations.mac-mini.system

# First-time bootstrap (nix-darwin not yet installed)
sudo nix run nix-darwin -- switch --flake .#mac-mini

# Daily rebuild (after first bootstrap)
sudo darwin-rebuild switch --flake .#mac-mini

# WSL rebuild
sudo nixos-rebuild switch --flake .#wsl

# Update all inputs
nix flake update

Shell

Fish (not zsh). All tool integrations use enableFishIntegration. Key files:

• home/shell/fish.nix — abbreviations, interactiveShellInit
• home/shell/tools.nix — fzf, atuin, zoxide (--cmd cd), direnv, bat, eza, yazi, btop

Home Manager option API (current)

These options were renamed in recent home-manager; use the new names:

• programs.git.settings.user.{name,email} (not userName/userEmail)
• programs.git.settings.* (not extraConfig)
• programs.delta.{enable,options} (not programs.git.delta.*)
• programs.delta.enableGitIntegration = true (must be explicit)
• programs.ssh.matchBlocks."*".addKeysToAgent (not top-level addKeysToAgent)
• programs.ssh.enableDefaultConfig = false (set explicitly)

Nix LSP

Uses nixd (not nil). nixd provides nixpkgs/option completion; nil does not. Installed via home/dev/languages.nix.

Formatter

nixfmt (was nixfmt-rfc-style, now unified). Run: nixfmt <file.nix>