nix-helper

name	Nix Helper
description	This skill should be used when the user asks to "add a new package", "configure a new program", "troubleshoot Nix build errors", "update flake inputs", "add a new host", "manage secrets with SOPS", "create out-of-store symlink", "use nvfetcher", "use claude-code-overlay", or mentions Nix, Home Manager, or nix-darwin configuration in this dotfiles repository.

Nix Helper

Provide guidance for managing Nix configurations in this dotfiles repository.

Configuration Overview

This dotfiles repository uses:

• Nix Flakes as the primary configuration entry point
• nix-darwin for macOS system-level configuration
• Home Manager for user-level configuration
• SOPS for secrets management
• nvfetcher for external packages not in nixpkgs
• claude-code-overlay for the claude-code package

Directory Structure

.
├── flake.nix              # Entry point (inputs, outputs, host configurations)
├── hosts/                 # Machine-specific configurations
│   ├── kohei-m4-mac-mini/ # Personal machine config
│   └── SC-N-843/          # Work machine config
├── nix-darwin/            # System-level macOS configurations
│   ├── default.nix        # Full configuration (personal machines)
│   └── minimum-for-work.nix # Minimal configuration (work machines)
├── home-manager/          # User-level configurations
│   ├── programs/          # Individual program configurations
│   ├── pkgs/              # Package list (default.nix)
│   ├── services/          # User-level services
│   └── files.nix          # Out-of-store symlink configuration
├── configs/               # Raw configuration files (Neovim, WezTerm, etc.)
├── secrets/               # SOPS-encrypted secrets
└── _sources/              # Auto-generated by nvfetcher

Common Tasks

Adding a New Package

Edit home-manager/pkgs/default.nix:

home.packages = with pkgs; [
  # ... existing packages
  new-package-name
];

See references/package-management.md for nvfetcher and external package patterns.

Adding a New Program Configuration

1. Create directory: home-manager/programs/<program-name>/
2. Create default.nix:

{ pkgs, ... }:
{
  programs.<program-name> = {
    enable = true;
    # Configuration options
  };
}

3. Import in home-manager/programs/default.nix:

let
  new-program = import ./new-program { inherit pkgs; };
in
[
  # ... existing programs
  new-program
]

See examples/new-program.nix.example for complete examples.

Adding Config Files with Out-of-Store Symlinks

Use out-of-store symlinks for configs that need editing without Nix rebuild.

1. Place files in configs/.config/<app-name>/
2. Edit home-manager/files.nix:

xdg.configFile."app-name" = {
  source = symlink /${rootDir}/.config/app-name;
  recursive = true;
};

See examples/out-of-store-symlink.nix.example for patterns.

Working with Secrets

Edit encrypted secrets:

sops secrets/default.yaml

Define in module:

sops.secrets.my-secret = { };

Use the secret path:

config.sops.secrets.my-secret.path

See references/secrets-management.md for detailed SOPS workflow.

Building and Applying Changes

# Apply configuration for specific host
sudo darwin-rebuild switch --flake .#kohei-m4-mac-mini
sudo darwin-rebuild switch --flake .#SC-N-843

# Format all Nix and Lua files
nix fmt

# Update all flake inputs
nix run .#update

# Run pre-commit hooks
nix develop -c pre-commit run --all-files

Key Patterns

userConfig Pattern

Each host defines a userConfig object passed to all modules:

userConfig = {
  username = "thinceller";
  homeDir = "/Users/${username}";
  hostname = "kohei-m4-mac-mini";
  dotfilesDir = homeDir + "/.dotfiles";
};

Access in modules via specialArgs:

{ userConfig, ... }:
{
  home.username = userConfig.username;
}

Module Import Pattern

Programs return lists for flexible composition:

# home-manager/default.nix
imports = programs ++ files ++ packages ++ services;

External Package Pattern (nvfetcher)

1. Define in nvfetcher.toml
2. Run nvfetcher to generate _sources/generated.nix
3. Import and use:

sources = pkgs.callPackage ../_sources/generated.nix { };
package = sources.package-name;

See references/package-management.md for detailed examples.

Troubleshooting

Build Errors

# Validate flake
nix flake check

# Show detailed error
nix build --show-trace

# Test configuration without applying
darwin-rebuild build --flake .#<hostname>

Common Issues

Issue	Solution
Package not found	Verify name in nixpkgs or use nvfetcher
Import errors	Check module path and return type (list vs attrset)
Symlink conflicts	Remove existing files before rebuild
SOPS decryption fails	Verify age key at ~/.config/sops/age/keys.txt

Flake Lock Updates

# Update specific input
nix flake lock --update-input <input-name>

# Update all inputs
nix run .#update

Adding a New Host

1. Create hosts/<hostname>/default.nix
2. Define userConfig:

userConfig = {
  username = "username";
  homeDir = "/Users/${username}";
  hostname = "<hostname>";
  dotfilesDir = homeDir + "/.dotfiles";
};

3. Choose nix-darwin module (full or minimum-for-work)
4. Add to flake.nix darwinConfigurations

See examples/new-host.nix.example for complete template.

Additional Resources

• references/package-management.md - nvfetcher, claude-code-overlay, external packages
• references/secrets-management.md - SOPS workflow and best practices
• references/home-manager-patterns.md - Program configuration patterns
• examples/new-program.nix.example - Program configuration template
• examples/new-host.nix.example - Host configuration template
• examples/out-of-store-symlink.nix.example - Symlink configuration patterns