nixos-cesium/CLAUDE.md

CLAUDE.md

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

What This Is

Personal NixOS system configuration for host cesium — an x86_64 desktop workstation with NVIDIA GPU. Uses NixOS with Flakes and Home Manager. NixOS version is locked to 25.11.

The project root is /mnt/data/nixos/. The actual NixOS configuration lives in the nixos/ subdirectory and is synced to /etc/nixos/ via make sync-etc, or built directly from nixos/ via make rebuild.

Commands

# Rebuild from ./nixos directly (no sync to /etc/nixos)
make rebuild

# Rebuild after upgrading flake inputs (updates flake.lock)
make upgrade

# Sync nixos/ to /etc/nixos and rebuild
make sync-etc

# Sync nixos/ to /etc/nixos and upgrade flake inputs
make upgrade-etc

# Dry-run sync to preview file changes
make sync-etc-dry-run

# Validate all .nix files (runs automatically as pre-commit hook)
make test

# Optimize store and garbage collect
make cleanup

Architecture

Entry point is nixos/flake.nix, which defines the cesium NixOS configuration:

nixos/flake.nix                   # Flake: inputs (nixpkgs 25.11, home-manager, nix-flatpak, unstable)
nixos/configuration.nix           # Top-level: imports all modules, enables Home Manager
├── hardware-configuration.nix    # Auto-generated (gitignored), host hardware
├── cesium.nix                    # Host-specific: NVIDIA drivers, hostname, firewall ports
├── common.nix                    # System-wide: bootloader, locale, GNOME, PipeWire, packages
├── mounts.nix                    # CIFS/SMB mounts to TrueNAS (automount with systemd)
├── services.nix                  # Docker (custom data root /home/docker), ddev
├── users/sebastian.nix           # User account, groups, SSH askpass
├── home.nix                      # Home Manager: apps, shell, git, scripts, Flatpak
├── programs.nix                  # Home Manager: git, shell programs config
├── dconf.nix                     # Home Manager: GNOME dconf settings
├── scripts.nix                   # Custom shell scripts (composer, lazydocker, gclb)
├── flakes.nix                    # Extra flake-based packages (e.g. Hytale launcher)
├── vm-guest.nix                  # Optional: SPICE agent for VM clipboard/file sharing
└── vm-host.nix                   # Optional: KVM/QEMU host with libvirtd, virt-manager

Supporting files in nixos/config/:

• p10k.zsh — Powerlevel10k prompt config
• zsh-custom.zsh — Custom zsh configuration
• crest_iv_black-cut.jpg — Wallpaper

Key design patterns:

• cesium.nix contains all host-specific hardware config (NVIDIA, hostname, ports)
• common.nix handles system-level config (boot, locale, desktop, audio, auto-updates, GC)
• home.nix handles user-level config via Home Manager (applications, shell, GTK theme, Flatpak)
• programs.nix and dconf.nix split out Home Manager programs and GNOME settings
• scripts.nix defines Docker-wrapped CLI tools using writeShellScriptBin
• mounts.nix uses systemd automount with 60s idle timeout for TrueNAS SMB shares
• vm-guest.nix and vm-host.nix are optional modules (not imported by default)
• nixpkgs-unstable overlay is used selectively (e.g. rustdesk-flutter)

Conventions

• Commit messages use [TASK] prefix (e.g., [TASK] Add filemounts)
• Formatting: 2-space indentation for .nix files, 4-space for everything else (see .editorconfig)
• Unfree packages are allowed (nixpkgs.config.allowUnfree = true)
• hardware-configuration.nix is gitignored — it's auto-generated per machine