nixos-configs/CLAUDE.md

CLAUDE.md

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

Repository Overview

This is a NixOS configuration repository using flakes, managing multiple machines and home-manager configurations. The repository follows a modular architecture with reusable "roles" that can be composed for different machines.

Architecture

Flake Structure

• flake.nix: Main entry point defining inputs (nixpkgs, home-manager, plasma-manager, etc.) and outputs for multiple NixOS configurations
• Machines: nix-book, boxy, wixos (WSL configuration)
• Home configurations: Standalone home-manager configuration for user johno

Directory Structure

• machines/: Machine-specific configurations with hardware-configuration.nix
• roles/: Modular system configurations (audio, bluetooth, desktop, users, etc.)
• home/: Home Manager configurations and user-specific modules
• home/modules/: User environment modules (emacs, i3+sway, plasma-manager, tmux)
• packages/: Custom package definitions

Role-Based Configuration System

The repository uses a custom "roles" system where each role is a NixOS module with enable options:

• roles.desktop: Desktop environment with sub-options for X11, Wayland, KDE, gaming, SDDM
• roles.audio: Audio configuration
• roles.bluetooth: Bluetooth support
• roles.users: User account management
• roles.virtualisation: Virtualization setup
• roles.kodi: Kodi media center

Example role usage in machine configuration:

roles = {
  audio.enable = true;
  desktop = {
    enable = true;
    gaming = true;
    kde = true;
    wayland = true;
  };
  users.enable = true;
};

Common Commands

Building and Switching Configurations

# Build and switch to a specific machine configuration
sudo nixos-rebuild switch --flake .#<hostname>

# Build without switching
nixos-rebuild build --flake .#<hostname>

# Build home-manager configuration only
home-manager switch --flake .#johno

Available Machine Configurations

• nix-book: Uses home/home-nix-book.nix
• boxy: Gaming desktop with AMD GPU, uses home/home.nix
• wixos: WSL configuration, uses home/home.nix

Flake Operations

# Update flake inputs
nix flake update

# Check flake
nix flake check

# Show flake info
nix flake show

Bootstrap New Machine

Use the provided bootstrap script:

sudo ./bootstrap.sh <hostname>

This script pulls from the remote git repository and applies the configuration.

Development Workflow

Adding New Machines

1. Create new directory in machines/<hostname>/
2. Add configuration.nix with role assignments
3. Include hardware-configuration.nix (generated by nixos-generate-config)
4. Add nixosConfiguration to flake.nix outputs

Adding New Roles

1. Create directory in roles/<role-name>/
2. Create default.nix with module definition using mkEnableOption
3. Add role import to roles/default.nix
4. Configure role options in machine configurations

Home Manager Modules

• Located in home/modules/
• Each module has its own default.nix
• Imported in main home configuration files

Key Configuration Details

• Experimental features: nix-command and flakes are enabled
• User: Primary user is johno with trusted-user privileges
• Locale: en_US.UTF-8, America/Los_Angeles timezone
• SSH: OpenSSH enabled on all configurations
• Garbage collection: Automatic, deletes older than 10 days
• Unfree packages: Allowed globally