nix-helper

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 edgepkgs", or mentions Nix, Home Manager, or nix-darwin configuration in this dotfiles repository.

⭐4stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026

When & Why to Use This Skill

The Nix Helper skill is a specialized assistant designed to manage and automate Nix-based dotfiles and system configurations. It streamlines the complexity of Nix Flakes, nix-darwin, and Home Manager, enabling users to maintain reproducible development environments, manage software packages efficiently, and handle secure secrets. By providing structured guidance on configuration patterns and troubleshooting, it significantly enhances developer productivity within the Nix ecosystem.

Use Cases

  • Automating the addition and configuration of new software packages across multiple machines using Nix Flakes and Home Manager.
  • Managing macOS system-level configurations and user-level program settings through a unified nix-darwin and Home Manager workflow.
  • Securing sensitive credentials and API keys within dotfiles using SOPS-encrypted secrets management.
  • Troubleshooting complex Nix build errors and validating flake configurations to ensure environment stability.
  • Synchronizing external packages and bleeding-edge software versions using nvfetcher and edgepkgs overlays.
  • Rapidly bootstrapping new development hosts by defining machine-specific configurations and user profiles.
nameNix Helper
descriptionThis 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 edgepkgs", 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
  • edgepkgs overlay for bleeding-edge packages

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
];

For bleeding-edge packages, use the edgepkgs overlay:

home.packages = [
  pkgs.edge.package-name  # From nixpkgs HEAD
];

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
  };
}
  1. 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.

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";
};
  1. Choose nix-darwin module (full or minimum-for-work)
  2. Add to flake.nix darwinConfigurations

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

Additional Resources

  • references/package-management.md - nvfetcher, edgepkgs, 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