nixos/AGENTS.md

AGENTS.md

Overview

This repository contains NixOS configurations for multiple machines using flakes, home-manager, and sops-nix for secrets.

Working with this Repository

DO

• Use nix fmt or nix fmt . to format files before committing (uses nixfmt-tree)
• Test builds with nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel
• Use the included devShell run nix develop to get formatting and linting tools
• When adding packages, check both overlays in flake.nix and home/programs/
• Follow the directory structure: hosts/ for system configs, home/ for home-manager configs
• CRITICAL: When adding NEW files, run git add <newfile> BEFORE building. Nix flakes ignore untracked files in the build context, so newly added files won't be copied and builds will fail until they're git-tracked

DON'T

• Don't work directly on master branch, always create a new branch if editing something
• Don't run nix flake update to update inputs, this should only be done by the user manually
• Don't directly edit files in secrets/ - they should be manually managed by the user
• Don't add secrets to Git
• Don't format with tools other than nix fmt (the formatter is defined in flake.nix)
• Don't modify .sops.yaml or any secrets, ask the user to do it manually
• Don't use nix-shell directly - use nix develop for the devShell environment
• Don't skip builds after configuration changes - test before pushing
• Don't mix stable and unstable packages arbitrarily in the same expression
• Don't commit without running nix fmt - formatted Nix is required
• Don't try to build with newly created but untracked files - nix build will fail to find them

Specific Patterns

Adding a New Program

- DO add to home/packages if no nixos or home-manager options are used.

• DO create a subdirectory in home/programs/ if nixos or home-manager options are used.
• DO git add the new configuration files before attempting to build
• DON'T add programs directly to user configs unless absolutely necessary

Modifying System Configuration

• DO check system/ for shared configs across hosts
• DO check individual hosts/<hostname>/ for host-specific overrides
• DON'T duplicate configuration - use system/ modules for shared settings

Working with Secrets

• DON'T add unencrypted secrets to the repository
• DON'T commit decrypted secrets
• DON'T add secrets, ask the user do it themselves

Testing

• DO run nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel to test
• DON'T push untested configuration changes
• DON'T attempt to build configurations with newly added but untracked files

Git

If change is small, and can be described sufficiently in the summary, dont add a long body to the commit, prefer just the summary if sufficient.

Commits should match the format: topic: description of change

Some examples:

• hyprland: convert deprecated windowrules
• packages: nixfmt-rfc-style renamed
• gunter: use beta nvidia driver

Repository Structure Guide

• flake.nix - Entrypoint, inputs, overlays, and configurations
• hosts/ - System-level NixOS configs per host
• home/ - Home-manager configs (programs, editor, window managers)
• system/ - Shared system modules (fonts, security, services)
• secrets/ - Encrypted secrets (managed by sops-nix)
• scripts/ - Utility scripts