sebastian/nixos-cesium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
main
nixos-cesium/CLAUDE.md
Sebastian Fischer 7a4283ba3a [TASK] Improve documentation
2026-02-10 20:07:06 +01:00

2.9 KiB
Raw Permalink Blame History

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 — a QEMU/KVM-virtualized x86_64 desktop workstation. Uses NixOS with Home Manager (channel-based, no Flakes). NixOS version is locked to 25.11.

Commands

# Rebuild and apply configuration (aliased as 'rebuild')
sudo nixos-rebuild switch

# Rebuild with package upgrades (aliased as 'update')
sudo nixos-rebuild switch --upgrade

# Test configuration without persisting (loads into current session only)
sudo nixos-rebuild test

# Build without applying (useful to check for errors)
sudo nixos-rebuild build

# Optimize store and garbage collect (aliased as 'ngc')
sudo nix-store --optimise && sudo nix-collect-garbage -d

# After first install: setup SMB credentials
sudo /etc/nixos/setup-smb-credentials.sh

Architecture

Entry point is config/configuration.nix, which imports all other modules:

config/configuration.nix          # Top-level: imports all modules, enables Home Manager
├── hardware-configuration.nix    # Auto-generated (gitignored), QEMU guest hardware
├── 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
│   └── imports home.nix          # Home Manager config for this user
├── home.nix                      # User environment: apps, shell, git, scripts, Flatpak
├── scripts.nix                   # Custom shell scripts (composer, lazydocker, gclb)
├── vm-guest.nix                  # Optional: SPICE agent for VM clipboard/file sharing
└── vm-host.nix                   # Optional: KVM/QEMU host with libvirtd, virt-manager

Key design patterns:

  • common.nix handles all system-level config (boot, locale, desktop, audio, auto-updates, garbage collection)
  • home.nix handles all user-level config via Home Manager (applications, shell aliases, git, vim, GTK theme, GNOME extensions, Flatpak activation scripts)
  • scripts.nix defines Docker-wrapped CLI tools (composer, lazydocker) and git helpers 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 in configuration.nix)

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