nixos/AGENTS.md

AGENTS.md - NixOS Configuration Repository

This file provides guidance for AI coding assistants working on this NixOS configuration.

Repository Overview

This is a NixOS system configuration for a desktop named "atlas". It uses flakes, modular organization, and includes customizations for gaming, development, and daily desktop use.

Build/Validation Commands

# Validate Nix syntax and build configuration
nix flake check

# Build the configuration (dry-run, doesn't activate)
nixos-rebuild dry-build --flake .

# Format all .nix files with nixfmt
nixfmt **/*.nix

# Check for common issues
nixos-rebuild dry-activate --flake .

Code Style Guidelines

File Organization

• Entry point: configuration.nix
• Flake definition: flake.nix
• Modular structure under modules/ organized by category:
  • core/ - Boot, system, networking, users, localization
  • hardware/ - GPU, audio, storage, power management
  • desktop/ - Window manager, apps, theming, portals
  • services/ - System services (avahi, printing, navidrome)
  • dev/ - Development tools, docker, shells
  • gaming/ - Steam, wine, gamemode

Module Pattern

Each module follows this structure:

# modules/<category>/<name>.nix
# Brief description of what this module configures
{
  config,
  pkgs,
  lib,
  inputs,      # Only if using flake inputs
  username,    # Custom arg passed from flake
  ...
}:

{
  # Configuration options here
}

Imports Pattern

default.nix files should only contain imports:

# modules/<category>/default.nix
{
  imports = [
    ./boot.nix
    ./system.nix
  ];
}

Formatting Rules

• Use 2-space indentation
• No tabs
• Keep lines under 100 characters when possible
• Add blank lines between logical sections
• Use descriptive comments with # Description format

Naming Conventions

• Module files: descriptive lowercase with hyphens (e.g., gpu-amd.nix)
• Use username variable from flake for user-specific paths
• Use lib.mkIf for conditional configuration
• Use lib.mkDefault for values that can be overridden

Input Handling

• Pass inputs from flake when accessing external packages
• Access input packages via: inputs.<name>.packages.${pkgs.stdenv.hostPlatform.system}.default
• Use pkgs.stdenv.hostPlatform.system for system-specific packages

Special Files

• hardware-configuration.nix - Generated by nixos-generate-config, DO NOT EDIT
• Scripts in scripts/ are bash installers (not part of NixOS config)
• Overlays contain patched Python scripts

Security Notes

• Never commit secrets, API keys, or tokens
• Sensitive files are in .gitignore
• Use proper LUKS encryption for swap and root partitions
• Secure Boot is enabled with custom Limine patches

Common Tasks

Adding a New Module

1. Create file in appropriate modules/<category>/ subdirectory
2. Add to the category's default.nix imports
3. Follow existing module structure and formatting
4. Add brief header comment describing purpose

Adding a Package

• System packages: add to environment.systemPackages in appropriate module
• User packages: prefer adding to system packages for shared use
• Flake packages: access via inputs with proper system attribute

Testing Changes

# Before committing, always verify syntax
nix flake check

# Build to catch evaluation errors
nixos-rebuild dry-build --flake .

Dependencies

External flake inputs:

• nixpkgs - Main NixOS packages (nixos-unstable)
• noctalia - Desktop shell
• nix-cachyos-kernel - CachyOS kernel with optimizations
• zen-browser - Zen browser
• opencode - AI coding assistant