| name | nix-management |
| description | Manage Nix flakes, NixOS or nix-darwin configurations, Home Manager setups, package overlays, dev shells, and lockfiles. Use when Codex needs to inspect or modify `flake.nix`, `flake.lock`, `*.nix`, `home-manager`, `nixos`, `darwin`, `overlays`, `packages`, `checks`, or `devShells`, and when validating changes with `nix flake check`, `nix build`, `nix develop`, `home-manager`, `darwin-rebuild`, or `nixos-rebuild`. |
Nix Management
Overview
Use this skill to make safe, targeted changes in Nix-based repositories. Start by discovering how the flake is structured, then choose the narrowest validation command that proves the requested change works before attempting any rebuild or switch step.
Quick Start
- Inspect the repo layout before editing. Look for
flake.nix, flake.lock, host or user modules, overlays, packages, checks, and devShells.
- Confirm the requested scope. Avoid changing unrelated modules, formatting, or lockfile pins unless the user asked for that.
- Make the smallest viable Nix edit.
- Validate with the least risky command that still exercises the change.
- Only run
switch, boot, or lockfile updates when the user asked for them or the task clearly requires them.
Use references/workflows.md for command selection and validation patterns. Use scripts/inspect_flake.py to summarize the local repo structure quickly.
Workflow
1. Inspect first
Prefer fast local inspection before running Nix commands:
- Use
rg --files to find *.nix, flake.nix, and flake.lock.
- Use
rg -n for darwinConfigurations, nixosConfigurations, homeConfigurations, devShells, packages, checks, and overlays.
- Run
python3 scripts/inspect_flake.py <repo> when you need a quick inventory of likely entry points.
If flake.nix is missing, adapt to a non-flake workflow instead of forcing flake commands.
2. Edit conservatively
- Preserve existing structure and style.
- Prefer modifying the nearest module that owns the behavior instead of centralizing unrelated logic.
- Avoid reformatting broad sections unless it is necessary for correctness or the repo already enforces formatting.
- Avoid updating
flake.lock unless the task explicitly involves input versions or a command regenerates it as a required side effect.
3. Pick the right validation
Choose the smallest command that proves the change:
- For syntax or evaluation confidence across the flake, prefer
nix flake check.
- For a package or derivation change, prefer
nix build on the specific output.
- For shell changes, prefer
nix develop or nix develop -c <command>.
- For Home Manager changes, prefer
home-manager build before home-manager switch.
- For nix-darwin changes, prefer
darwin-rebuild build --flake ... before darwin-rebuild switch.
- For NixOS changes, prefer
nixos-rebuild build --flake ... before nixos-rebuild switch or boot.
If a high-impact rebuild is the only meaningful validation, say so explicitly before running it.
4. Handle failures deliberately
- Read the first real evaluation error before changing code again.
- Distinguish syntax errors, missing attributes, wrong system names, infinite recursion, and option collisions.
- If the repo depends on secrets, private inputs, or machine-specific paths, explain the limitation and validate as far as the environment allows.
Safety Rules
- Never run
nix flake update or nix flake lock --update-input unless the user requested dependency updates.
- Never run
*-rebuild switch, home-manager switch, or other live-apply commands unless the user asked to apply the change.
- Prefer
build or check over switch.
- Call out when a command may download dependencies, rebuild many derivations, or mutate the working tree.
- Keep edits minimal in shared flake repos because one change can affect multiple hosts or users.
Common Tasks
Add or update a package
Find whether the package belongs in a host module, Home Manager module, overlay, or custom package set. Validate with a targeted build or the closest config build command.
Modify a dev shell
Inspect devShells outputs and any shell helpers. Validate with nix develop and a lightweight command that proves the tool is present.
Fix an attribute or option error
Trace the attribute path from the failing command back to the flake output or module that owns it. Prefer correcting the path or option merge logic over rewriting adjacent modules.
Update a pinned input
Only do this when requested. Update the smallest relevant input, inspect the resulting flake.lock diff, and rerun the narrowest validation that exercises the affected outputs.
References
