# 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:
```nix
roles = {
  audio.enable = true;
  desktop = {
    enable = true;
    gaming = true;
    kde = true;
    wayland = true;
  };
  users.enable = true;
};
```

## Common Commands

### Building and Switching Configurations
```bash
# 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
```bash
# 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:
```bash
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