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.

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