Imported from Rikand98/.nixos (AGENTS.md). Install upstream with npx skills add Rikand98/.nixos. Copyright stays with the author.

AGENTS.md - Development Guide for .nixos

This is a NixOS/nix-darwin configuration repository using flakes, Home Manager, and nixvim.

Build / Test Commands

Rebuild Commands

# Rebuild NixOS (Linux)
sudo nixos-rebuild switch --flake .#home-desktop

# Rebuild Darwin (macOS)
sudo darwin-rebuild switch --flake .#lysio-macbook

# Or use the aliases (from fish.nix)
nixosbuild  # Linux
darwinbuild # macOS

Flake Operations

# Update all flake inputs
nix flake update

# Evaluate flake (check for errors without building)
nix eval .#nixosConfigurations.home-desktop.config.system.build.toplevel.outPath

# Show flake outputs
nix flake show

Lint / Format Commands

Formatting

# Format all Nix files (uses nixfmt defined in flake.nix)
nix fmt

Linting

# Run nil (Nix language server) for LSP diagnostics
nil fmt .

# Check formatting without modifying
nixpkgs-fmt --check .

Development Shell

# Enter dev shell with formatting/linting tools
nix develop

# Tools available: just, nil, nixpkgs-fmt

Testing Single Modules

# Test a specific host configuration
nix build .#nixosConfigurations.home-desktop.config.system.build.toplevel.outPath --show-trace

# Dry-run rebuild (check for errors)
sudo nixos-rebuild dry-run --flake .#home-desktop

Code Style Guidelines

General Conventions

• Indent: 2 spaces (no tabs)
• Line length: Keep under 120 characters when practical
• Trailing commas: Always include (helps with diffs)
• Newlines: Unix (\n)

Nix File Structure

{ inputs, pkgs, host, username, ... }:
{
  imports = [
    ./module1.nix
    ./module2.nix
  ];

  # Option declarations
  option1 = "value";
  option2 = true;

  # Enable block for packages/programs
  programs = {
    example = {
      enable = true;
      settings = {
        key = "value";
      };
    };
  };
}

Imports Pattern

Always use inherit for passing inputs through modules:

{ inputs, pkgs, username, ... }:
{
  imports = [ ./default.nix ];
  
  home-manager.extraSpecialArgs = {
    inherit inputs username;
  };
}

Naming Conventions

• Files: kebab-case (niri-default.nix, conform-nvim.nix)
• Modules: default.nix for directory entry points
• Options: camelCase in NixOS, kebab-case in Home Manager options
• Variables: snake_case in Nix

Error Handling

• Use set -euo pipefail in shell scripts
• Always check for command existence: command -v foo >/dev/null
• Use lib.optionalAttrs for conditional attributes

Module Organization

modules/
├── core/
│   ├── nixos/          # NixOS-specific configs
│   │   ├── default.nix # Imports all nixos modules
│   │   ├── services.nix
│   │   └── system.nix
│   └── darwin/         # macOS-specific configs
└── home/
    ├── default.nix     # Home Manager entry
    ├── fish.nix        # Shell config
    ├── niri/           # Window manager
    └── nixvim/         # Neovim config
        └── plugins/    # Plugin modules

Host Configuration

{ pkgs, ... }:
{
  imports = [
    ./hardware-configuration.nix
    ../../modules/core/nixos
  ];

  # Host-specific settings
  powerManagement.cpuFreqGovernor = "performance";
}

Git Usage

# Stage and commit changes
git add -A
git commit -m "description of changes"

# Check status
git status

# View diff
git diff

Important Notes

• user_info.nix: Contains sensitive per-machine config (not committed)
• flake.lock: Auto-generated - don't manually edit
• hardware-configuration.nix: Generated by NixOS installer, must be copied to host directory

Editor Setup

This repo uses nixvim (Nix-based Neovim config). Key plugins: -conform-nvim: Auto-formatting on save

• treesitter: Syntax highlighting
• LSP via nixvim modules

VS Code users: Install Nix for VS Code extension for IDE support.