CLAUDE.md

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

Overview

This is "Atlas" - a modular, flake-based NixOS configuration for a desktop workstation. The system is AMD-specific (CPU + GPU) and optimized for gaming, development, and daily use.

Common Commands

# Test configuration without switching (validate before applying)
sudo nixos-rebuild test --flake .#nixos

# Apply configuration
sudo nixos-rebuild switch --flake .#nixos

# Build and set as boot default (without switching)
sudo nixos-rebuild boot --flake .#nixos

# Update all flake inputs
nix flake update

# Update specific input
nix flake lock --update-input nixpkgs

# Garbage collection
sudo nix-collect-garbage --delete-older-than 14d

Shell aliases are defined in modules/shell.nix: rebuild, rebuild-test, rebuild-boot, update, gc-nix.

Architecture

Entry Points:

flake.nix - Flake definition with inputs (nixpkgs unstable, nix-cachyos-kernel, noctalia shell, vicinae launcher)
configuration.nix - Main config that imports all modules, defines boot, networking, user, and nix settings
hardware-configuration.nix - Auto-generated by nixos-generate-config (do not edit manually)

Modular Structure: All feature configurations live in modules/ as standalone NixOS modules:

desktop.nix - XDG portals, Wayland, polkit, launcher (Vicinae)
gpu-amd.nix - AMD drivers, Vulkan, VA-API, CoreCtrl
gaming.nix - Steam, Gamemode, Wine/Proton, kernel tweaks
dev.nix - Docker, Node.js, Rust, build tools, CLI utilities
shell.nix - Fish shell config, aliases, plugins
services.nix - fstrim, zram, avahi, profile-sync-daemon, earlyoom
audio.nix, theming.nix, power.nix, virtualization.nix, navidrome.nix, apps.nix

Each module follows the pattern: { config, pkgs, lib, ... }: { ... }

Package Management Philosophy:

System packages (environment.systemPackages): Services, hardware support, desktop infrastructure, build tools
User packages (nix profile): GUI apps and fast-updating tools - managed independently with update-apps alias

Code Conventions

2-space indentation
Standard module signature: { config, pkgs, lib, ... }:
Package lists use with pkgs; [ ... ] syntax
Decorative comment separators (# ═══...) for major sections

Critical Rules

Never modify hardware-configuration.nix - it's auto-generated
Never change system.stateVersion (currently 26.05)
Always validate with rebuild-test before switching
User groups are distributed across modules (docker in dev.nix, gamemode in gaming.nix, corectrl in gpu-amd.nix, libvirtd in virtualization.nix)

Key System Details

Kernel: CachyOS with x86_64-v3 optimizations, scx_lavd scheduler
Desktop: Niri compositor, Ly display manager, Ghostty terminal
User: pinj with Fish shell (Zsh as fallback)
State Version: 26.05

2.9 KiB Raw Blame History