nixos/CLAUDE.md

CLAUDE.md

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

Common Commands

Building and Rebuilding Systems

# Rebuild NixOS configuration for current system
sudo nixos-rebuild switch --flake .

# Build for specific system
sudo nixos-rebuild switch --flake .#nate-work
sudo nixos-rebuild switch --flake .#nate
sudo nixos-rebuild switch --flake .#luci
sudo nixos-rebuild switch --flake .#jaci
sudo nixos-rebuild switch --flake .#scrappy
sudo nixos-rebuild switch --flake .#frame12

# Test configuration without switching
sudo nixos-rebuild test --flake .

# Check configuration without building
nix flake check

# Dry-run build specific host configuration (check for errors/warnings without building)
nix build .#nixosConfigurations.frame12.config.system.build.toplevel --dry-run
nix build .#nixosConfigurations.nate-work.config.system.build.toplevel --dry-run
nix build .#nixosConfigurations.nate.config.system.build.toplevel --dry-run

Package Management

# Update flake inputs
nix flake update

# Run garbage collection
nix-collect-garbage -d

# Check system generations
nixos-rebuild list-generations

# Rollback to previous generation
sudo nixos-rebuild switch --rollback

Home Manager

# Apply home manager configuration
home-manager switch --flake .

# For specific user configurations
home-manager switch --flake .#nate-work

Window Manager Configuration Validation

# Validate niri configuration
niri validate

# Validate sway configuration (if using sway)
sway --validate

# Validate hyprland configuration (if using hyprland) 
hyprctl reload  # This reloads and validates the config

# Check wayland compositor logs for errors
journalctl --user -u niri -f          # For niri
journalctl --user -u sway -f          # For sway  
journalctl --user -u hyprland -f      # For hyprland

Architecture Overview

This is a multi-user NixOS configuration repository using Nix flakes. The repository manages configurations for multiple machines and users across different environments.

Repository Structure

• flake.nix: Main flake configuration defining all system configurations
• {user}/: Individual user configuration directories (nate, nate-work, luci, jaci, scrappy)
• shared/: Shared modules and configurations across systems
• {user}/default.nix: System-level configuration for each user/machine
• {user}/desktop-configuration.nix: Desktop environment configuration
• {user}/modules/: User-specific modules and configurations
• {user}/dotfiles/: User dotfiles and application configurations

Key Components

System Configurations

Each system configuration follows this pattern:

• default.nix: Main system configuration with user settings, hostname, desktop environment
• desktop-configuration.nix: Desktop environment setup (Sway/Hyprland)
• modules/home-manager/home.nix: Home Manager configuration
• nixos/hardware-configuration.nix: Hardware-specific settings

Supported Desktop Environments

• Sway: Wayland compositor (default)
• Hyprland: Modern Wayland compositor
• Desktop choice configured via deskCfg.de option

User Management

• Custom main_user module handles user creation
• Desktop users get additional groups (video, audio, adbusers)
• Server users get minimal groups (wheel, networkmanager)

Package Management

• Stable packages from nixpkgs 25.05
• Unstable packages available via nixpkgs-unstable
• Catppuccin theme integration via catppuccin.nix
• NUR (Nix User Repository) overlay enabled

Configuration Patterns

User-Specific Settings

Each user configuration defines:

{
  userName = "username";
  fullName = "Full Name";
  email = "email@domain.com";
  hostName = "hostname";
  desktop = "sway" or "hyprland";
  gaming = true/false;
}

Module System

• Custom modules in modules/ directories
• Shared modules in shared/modules/
• Options defined with lib.mkOption
• Conditional configuration with lib.mkIf

Home Manager Integration

• Home Manager configurations in modules/home-manager/home.nix
• Dotfiles linked from dotfiles/ directories
• User packages defined in homePackages

Development Environment

Installed Development Tools

• Editors: Helix (default), Emacs
• Languages: Go, Python, Clojure, Nix
• LSPs: gopls, nil, bash-language-server, python-lsp-server
• Tools: Docker, distrobox, jq, make, cmake
• Version Control: Git with delta, direnv

Shell Configuration

• Default Shell: Zsh with Oh My Zsh
• Theme: half-life
• Plugins: git, ssh-agent
• Aliases: Modern Unix tools (lsd, bat, ripgrep, fd, fzf)

Security and Maintenance

Automatic Updates

• auto-update.nix module for automatic system updates
• Garbage collection configured weekly
• Boot loader limited to 5 generations
• Store optimization enabled

Security Features

• ClamAV antivirus on work systems
• Gnome Keyring for SSH secrets
• Firewall configuration for servers
• Initial password set to "password" (should be changed)

Server Configuration

For server deployments, use shared/server-configuration.nix which provides:

• SSH server option
• NFS server with configurable exports
• Syncthing for file synchronization
• Radicale CalDAV server
• Printer sharing via CUPS/Avahi

Special Features

Claude Code Integration

• Work profile: claudew command (uses AWS Bedrock)
• Personal profile: claudep command (uses standard API)
• Configuration directories: /home/nate/.claude-work and /home/nate/.claude-personal

Catppuccin Theme

• Consistent theming across applications
• Macchiato variant with lavender accent
• GTK, Qt, and terminal theme integration