nixos-advisor

clempat's avatarfrom clempat

NixOS configuration advisor using MCP tools. Use when helping with NixOS/Home Manager configs, searching packages/options, or providing NixOS-specific guidance. Validates packages exist before suggesting them.

⭐6stars🔀0forks📁View on GitHub🕐Updated Dec 19, 2025⬇️5downloads

When & Why to Use This Skill

The NixOS Advisor is a specialized Claude skill designed to streamline NixOS and Home Manager configuration management. By leveraging real-time MCP tools, it allows users to search for packages, verify configuration options, and generate accurate Nix expressions. This tool ensures that suggested packages exist and are compatible with specific channels (stable or unstable), significantly reducing the trial-and-error often associated with NixOS system administration and Infrastructure as Code (IaC) workflows.

Use Cases

  • Package Discovery & Validation: Quickly search for NixOS packages or Home Manager options and verify their existence and metadata before adding them to your configuration files.
  • Automated Configuration Generation: Generate ready-to-use Nix code snippets for system services, user environments, and hardware-specific settings based on verified expert guidance.
  • Multi-Platform Management: Seamlessly manage configurations across different environments including NixOS, nix-darwin for macOS, and standalone Home Manager setups using a unified interface.
  • Channel & Version Tracking: Monitor NixOS channel statistics and package versions to ensure your system stays updated with the latest stable releases or cutting-edge unstable packages.
  • Troubleshooting & Optimization: Use detailed package and option info to debug configuration conflicts and optimize system performance according to NixOS best practices.
namenixos-advisor
descriptionNixOS configuration advisor using MCP tools. Use when helping with NixOS/Home Manager configs, searching packages/options, or providing NixOS-specific guidance. Validates packages exist before suggesting them.

NixOS Configuration Advisor

Provides expert guidance for NixOS and Home Manager configurations using the NixOS MCP server tools.

MCP Tools Available

The nixos MCP server provides these tools:

  • nixos_search - Search NixOS packages, options, programs, or flakes
  • nixos_info - Get detailed info about a package or option
  • nixos_channels - List available NixOS channels
  • nixos_stats - Get statistics for a channel
  • home_manager_search - Search Home Manager options
  • home_manager_info - Get detailed info about Home Manager option
  • darwin_search - Search nix-darwin options (macOS)
  • darwin_info - Get info about nix-darwin option

Required Workflow

ALWAYS follow this process when suggesting packages or options:

  1. Search first: Use MCP tools to verify package/option exists
  2. Check details: Get full info including description and version
  3. Verify channel: Note if package is in stable/unstable
  4. Suggest config: Provide NixOS/Home Manager configuration
  5. Rebuild command: Provide appropriate rebuild command

Example: Adding a Package

User asks: "Add Firefox"

  1. Search: nixos_search(query="firefox", search_type="packages")
  2. Verify: nixos_info(name="firefox", type="package")
  3. Check channel availability and current version
  4. Suggest config:
environment.systemPackages = with pkgs; [
  firefox
];
  1. Provide rebuild: sudo nixos-rebuild switch --flake .#hostname

Example: Configuring Options

User asks: "Enable SSH"

  1. Search: nixos_search(query="openssh", search_type="options")
  2. Get details: nixos_info(name="services.openssh.enable", type="option")
  3. Suggest config:
services.openssh = {
  enable = true;
  settings = {
    PermitRootLogin = "no";
    PasswordAuthentication = false;
  };
};

Example: Home Manager

User asks: "Configure git"

  1. Search: home_manager_search(query="git")
  2. Get info: home_manager_info(name="programs.git.enable")
  3. Suggest config:
programs.git = {
  enable = true;
  userName = "Your Name";
  userEmail = "your.email@example.com";
};

Channel Awareness

  • Unstable: Latest packages, may have breaking changes
  • Stable (24.11, etc): Tested releases, recommended for production
  • Check availability: Some packages only in unstable

Use nixos_channels() to see available channels and their status.

Best Practices

DO:

  • Always validate packages/options with MCP before suggesting
  • Check channel differences and inform user
  • Provide complete, working configuration examples
  • Use pkgs.unstable.package syntax when needed for newer versions
  • Include rebuild commands appropriate for the system type

DON'T:

  • Never suggest packages without MCP verification
  • Don't assume package names (firefox-esr vs firefox)
  • Don't skip checking if option exists
  • Don't suggest destructive commands without warning

System Detection

Detect system type from context:

  • NixOS: sudo nixos-rebuild switch --flake .#hostname
  • Darwin (macOS): darwin-rebuild switch --flake .#hostname
  • Home Manager standalone: home-manager switch --flake .#user@hostname

Flake Structure

User's typical flake structure:

.
├── flake.nix
├── host/
│   ├── nixos/
│   └── darwin/
├── home/
│   ├── common/
│   └── users/
└── modules/

Common Tasks

Search packages

nixos_search(query="package-name", search_type="packages", limit=10)

Find options

nixos_search(query="service", search_type="options", limit=20)

Get package details

nixos_info(name="package-name", type="package")

Check Home Manager option

home_manager_info(name="programs.package.enable")

List channels

nixos_channels()

Error Handling

  • Package not found: Search with broader terms, check spelling
  • Option doesn't exist: May be in different module or named differently
  • Channel mismatch: Suggest switching or using unstable overlay

Notes

  • User prefers unstable channel for newer packages
  • Configuration files use 2-space indentation
  • Follow existing code style in user's config
  • Be concise in explanations per user preference