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
```bash
nix fmt                  # Format all Nix files (uses nixfmt-tree)
nix fmt .                # Same as above
```

### Building & Testing
```bash
# 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, building for just the relevant host is enough.
Otherwise, build both. **Always ask before building gunter** — it takes a long time.

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
```bash
# 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
```bash
# 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`:
```nix
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