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
```bash
# 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
```bash
# 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
```bash
# Apply home manager configuration
home-manager switch --flake .

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

### Window Manager Configuration Validation
```bash
# 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:
```nix
{
  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