nixos/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a NixOS configuration repository using flakes for managing multiple machines (gunter, magicman). It uses home-manager for user configurations and sops-nix for secrets management. Custom packages from private git repositories are integrated via flake inputs and overlays.

Essential Commands

Formatting

nix fmt                  # Format all Nix files (uses nixfmt-tree)
nix fmt .                # Same as above

Building & Testing

# Test build a specific host configuration
nix build .#nixosConfigurations.gunter.config.system.build.toplevel
nix build .#nixosConfigurations.magicman.config.system.build.toplevel

# Enter development shell (includes act, actionlint, yamllint)
nix develop

If config clearly only affects one host, bulding for just the relevant host is enough. Otherwise, build both.

If moving things around, you can use nix eval before and after changes to check that things remain the same.

nix eval .#nixosConfigurations.magicman.config.nix.settings.substituters --json | jq

Comparing with Running System

# Build and compare against currently running system
nixos-rebuild build --flake . && nvd diff /run/current-system result

This shows package version changes, added/removed packages, and closure size differences between what's currently running and the repo configuration.

Common Operations

# Check flake without building
nix flake check

# Show flake outputs
nix flake show

Architecture

Flake Structure

• Inputs: Uses both stable (nixos-25.05) and unstable nixpkgs channels
• Overlays: overlay-stable provides pkgs.stable for stable packages; custom overlays integrate private packages (ghettoptt, huecli, nixprstatus, natstonotify, nix-packages)
• System: x86_64-linux primary, with multi-platform devShell support

Directory Organization

├── flake.nix                 # Main entrypoint with overlays and host definitions
├── hosts/                    # Per-host system configurations
│   ├── gunter/              # Desktop with multi-monitor, nvidia, steam
│   └── magicman/            # Laptop configuration
├── home/                     # Home-manager user configurations
│   ├── hosts/               # Per-host user settings (imports packages + programs)
│   ├── editor/              # Neovim configuration
│   ├── hyprland/            # Wayland compositor with custom options
│   ├── packages/            # Simple packages (no options)
│   ├── programs/            # Programs with home-manager options (dunst, git, firefox, etc.)
│   ├── services/            # User services (backup, ghettoptt, natstonotify)
│   ├── scripts/             # User scripts
│   ├── sops/                # User secrets configuration
│   ├── ssh/                 # SSH configuration
│   └── zsh/                 # Shell configuration
├── system/                   # Shared system-level modules
│   ├── monitoring/          # logs.nix, metrics.nix
│   ├── fonts.nix            # Font configuration
│   ├── locale.nix           # Localization settings
│   ├── users.nix            # User account definitions
│   └── ...                  # Other system modules
└── secrets/                  # SOPS-encrypted secrets (don't modify)

Configuration Pattern

• Each host's default.nix imports: configuration.nix, hardware-configuration.nix, host-specific modules, ../../system, and ../../home/hosts/<hostname>
• Home-manager imports are in home/hosts/<hostname>/default.nix which imports editor, hyprland, packages, programs, services, etc.
• Shared system config goes in system/, host-specific overrides in hosts/<hostname>/

Hyprland Custom Options

The hyprland module in home/hyprland/default.nix provides custom options:

• hyprland.monitors: List of monitor configurations
• hyprland.extraEnv: Environment variables
• hyprland.extraKeybinds: Additional keybindings
• hyprland.extraWorkspaces: Named workspace definitions
• hyprland.monitorVariables: Monitor name variables (e.g., $mon_left)
• hyprland.enableGrimblast, hyprland.enableWacom, hyprland.cursorNoHardware: Feature flags

Critical Workflow Rules

Git Tracking for New Files

CRITICAL: Nix flakes ignore untracked files. When adding new files, run git add <newfile> BEFORE attempting to build. Builds will fail with "file not found" errors until files are git-tracked.

Branching

Always create a new branch for changes. Never work directly on master branch.

Formatting

Always run nix fmt before committing. Formatted Nix code is required.

Commit Messages

Format: topic: description

Examples:

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

Keep summaries concise. Only add commit body if needed for context.

Forbidden Operations

• Don't run nix flake update (user manages input updates)
• Don't edit files in secrets/ directory
• Don't modify .sops.yaml
• Don't use nix-shell (use nix develop instead)
• Don't mix stable/unstable packages arbitrarily
• Don't skip builds after configuration changes

Adding Programs

• If no NixOS/home-manager options needed: add to home/packages
• If using options: create subdirectory in home/programs/
• Remember to git add new files before building

Package Management

Using Stable Packages

The overlay-stable provides access to stable nixpkgs via pkgs.stable:

environment.systemPackages = [ pkgs.stable.somePackage ];

Do not use packages from stable unless explicitly requested.

Custom Packages

Custom packages from private repos are available via overlays:

• pkgs.ghettoptt
• pkgs.huecli
• pkgs.nixprstatus
• pkgs.natstonotify
• Plus packages from nix-packages overlay