Rename CLAUDE.md to AGENTS.md

2025-11-10 08:12:19 -08:00
parent 79ae42f41d
commit d62bae0ddb
1 changed files with 0 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,177 @@
+# 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), `zix790prors`, `live-usb`, `johno-macbookpro` (Darwin/macOS)
+- **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
+- `roles.nvidia`: NVIDIA GPU configuration
+- `roles.printing`: Printing support (CUPS)
+- `roles.spotifyd`: Spotify daemon
+- `roles.btrfs`: Btrfs filesystem configuration
+- `roles.nfs-mounts`: NFS mount configuration
+- `roles.darwin`: macOS-specific configurations
+
+Example role usage in machine configuration:
+```nix
+roles = {
+  audio.enable = true;
+  desktop = {
+    enable = true;
+    gaming = true;
+    kde = true;
+    wayland = true;
+  };
+  users.enable = true;
+};
+```
+
+### Home-Manager Role System
+The repository also uses a modular home-manager role system for user-space configuration:
+
+**Available Home Roles:**
+- `home.roles.base`: Core CLI tools, git, ssh, bash, rbw (enabled everywhere)
+- `home.roles.desktop`: GUI applications, Firefox, KDE services
+- `home.roles.office`: LibreOffice, OpenSCAD (heavy packages)
+- `home.roles.media`: VLC, Jellyfin, Moonlight (media consumption)
+- `home.roles.development`: Custom packages, kubectl, development tools
+- `home.roles.communication`: Element, Nextcloud Talk, Google cookie tools
+- `home.roles.sync`: Syncthing service and tray (for file synchronization)
+- `home.roles.kdeconnect`: KDE Connect for device integration
+- `home.roles.gaming`: Gaming applications (future expansion)
+
+**Role-Based Home Configurations:**
+- `home-desktop.nix`: Full-featured desktop for development workstations
+- `home-media-center.nix`: Living room media consumption and gaming setup (boxy)
+- `home-laptop-compact.nix`: Essential tools only, excludes office/media for storage constraints (nix-book)
+- `home-live-usb.nix`: Minimal setup for live environments, no persistent services
+- `home-darwin-work.nix`: macOS work laptop configuration
+
+**Machine-Specific Role Usage:**
+- **nix-book**: Compact laptop → excludes office/media roles due to SSD space constraints
+- **boxy**: Living room media center → optimized for media consumption, excludes sync/office (shared machine)
+- **zix790prors**: All-purpose workstation → full desktop experience with all roles enabled
+- **wixos**: WSL2 development → full desktop experience, inherits from zix790prors Windows host
+- **live-usb**: Temporary environment → only base + desktop roles, no persistent services
+- **johno-macbookpro**: macOS work laptop → Darwin-specific configuration with development tools
+
+## Common Commands
+
+### Building and Switching Configurations
+
+**NixOS (Linux):**
+```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
+```
+
+**Darwin (macOS):**
+```bash
+# Build and switch to Darwin configuration
+darwin-rebuild switch --flake .#johno-macbookpro
+
+# Build without switching
+darwin-rebuild build --flake .#johno-macbookpro
+```
+
+### Available Machine Configurations
+- `nix-book`: Compact laptop with storage constraints, uses `home/home-laptop-compact.nix`
+- `boxy`: Shared living room media center/gaming desktop with AMD GPU, uses `home/home-media-center.nix`
+- `zix790prors`: Powerful all-purpose workstation (gaming, 3D modeling, development), dual-boots Windows 11 with shared btrfs /games partition, uses `home/home-desktop.nix`
+- `wixos`: WSL2 development environment running in Windows partition of zix790prors, uses `home/home-desktop.nix`
+- `live-usb`: Bootable ISO configuration, uses `home/home-live-usb.nix`
+- `johno-macbookpro`: macOS work laptop, uses `home/home-darwin-work.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.
+
+### Build Live USB ISO
+Use the provided script to build a bootable ISO:
+```bash
+./build-liveusb.sh
+```
+Creates an ISO suitable for Ventoy and other USB boot tools in `./result/iso/`.
+
+## Development Workflow
+
+### Adding New Machines
+
+**NixOS:**
+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
+
+**Darwin (macOS):**
+1. Create new directory in `machines/<hostname>/`
+2. Add `configuration.nix` with Darwin role assignments
+3. Add darwinConfiguration 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
+
+## Important Notes
+
+- **Sudo access**: Claude Code does not have sudo access. Ask the user to run elevated commands like `sudo nixos-rebuild switch`