Nixos Config

NixOS Configuration Skill

Announce at start: "I'm using the nixos-config skill to work with your Nix configuration."

Critical Reminders

• Flakes only — never use channels or nix-env
• Declarative always — never use imperative approaches when declarative solutions exist
• jj new before building — new files must be tracked; run jj new so they appear in git HEAD
• Always build-test — never consider the task complete without a successful build
• Clean up result symlinks — remove any result symlinks created during builds

Quick Reference

Workflow

Phase 1: Analyze Existing Configuration

Before making changes, understand the current setup:

1. Read flake.nix to understand inputs, outputs, and structure
2. Identify the module organization pattern (flat vs nested, custom namespaces like mynix)
3. Check for existing conventions:
   • Option naming patterns
   • Module enable/disable patterns
   • Import structure
   • Custom library functions
4. Note the hostname(s) and user(s) configured

Phase 2: Plan Changes

Determine scope and approach:

1. NixOS vs Home Manager — system-level services and kernel config go in NixOS modules; user programs, dotfiles, and user services go in Home Manager
2. New module vs existing — prefer extending existing modules unless the feature is clearly separate
3. Option design — plan option names, types, and defaults that match existing conventions
4. Explain the planned changes to the user before implementing

Phase 3: Implement

Write the configuration following Nix best practices:

• Use lib.mkEnableOption for boolean toggles
• Use lib.mkOption with proper types (types.str, types.listOf, types.attrsOf, etc.)
• Use lib.mkIf for conditional configuration
• Use lib.mkDefault for defaults that users can override
• Use lib.mkForce sparingly and only when necessary
• Use lib.mkMerge to combine multiple config blocks
• Use lib.assertMsg for meaningful error messages on invalid config
• Respect the project's existing conventions and namespaces
• Add description strings to custom options

Phase 4: Validate and Build

1. If new files were created, run jj new so they are tracked
2. Build and test:
   • NixOS: sudo nixos-rebuild test --flake .#<hostname>
   • Home Manager: home-manager build --flake .#user@hostname --no-out-link
3. Run nix flake check if structural changes were made to the flake
4. Clean up any result symlinks: rm -f result
5. Squash related changes if needed: jj squash

Phase 5: Troubleshoot If Build Fails

If the build fails, follow this process:

1. Parse the error message — identify the failing module, option, or derivation
2. Use debugging tools:
   • nix-instantiate --eval to test expressions in isolation
   • nix repl to interactively explore values
   • nix show-derivation to inspect build dependencies
3. Fix the issue and rebuild
4. Repeat until the build succeeds

Error Handling

Common Failure Patterns

Build Fails After Adding New Files

This is the most common issue. New files are not visible to the Nix evaluator until they are tracked:

jj new          # snapshot new files into git HEAD
# then rebuild

Remember to squash related changes afterward if needed.

Key Principles

1. Declarative — every configuration choice should be expressed declaratively in Nix
2. Minimal changes — make targeted changes that integrate with existing patterns
3. Validate before done — never claim completion without a passing build
4. Respect conventions — follow the project's established module structure, naming, and namespaces
5. Explain changes — describe what was changed and why, highlight breaking changes or migration needs

Resources

Reference materials are available in the references/ directory:

• nix-language.md — Nix language syntax and builtins
• flake-patterns.md — Flake structure, inputs, and overlays
• nixos-modules.md — Module structure, option declarations, and config patterns
• home-manager.md — Home Manager modules, programs, and services
• troubleshooting.md — Error catalog, debugging workflow, and migration patterns