From 9ed54ac3b980848a142165ad5dd8c4af92923e1e Mon Sep 17 00:00:00 2001 From: Christian Date: Tue, 12 May 2026 20:19:34 -0500 Subject: Claude --- CLAUDE.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 CLAUDE.md (limited to 'CLAUDE.md') diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..08ef55a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,168 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +This is a NixOS flake-based configuration managing three machines: desktop, laptop, and hyper-v. The configuration uses home-manager for user-level package and dotfile management, with a modular architecture separating system-level and user-level concerns. + +## Common Commands + +### Rebuild System +```bash +rebuild # Alias for: sudo nixos-rebuild switch --flake ~/.config/nixos +``` + +### Format Nix Files +```bash +nixfmt .nix +``` + +### Flake Operations +```bash +nix flake update # Update all flake inputs +nix flake lock --update-input # Update specific input +nix flake show # Show flake outputs +nix flake check # Validate flake +``` + +### Build Specific Host +```bash +sudo nixos-rebuild switch --flake ~/.config/nixos#desktop +sudo nixos-rebuild switch --flake ~/.config/nixos#laptop +sudo nixos-rebuild switch --flake ~/.config/nixos#hyper-v +``` + +## Architecture + +### Two-Layer Module System + +The configuration has a strict separation between **system-level modules** (in `modules/`) and **user-level modules** (in `modules/home/`): + +1. **System-level modules** (`modules/*.nix`): + - Import home-manager as a NixOS module + - Configure system-wide settings + - Import corresponding user-level modules via `home-manager.users.christian.imports` + +2. **User-level modules** (`modules/home/*.nix`): + - Contain home-manager configuration only + - Installed via system-level module imports + - Should NOT be directly imported into host configurations + +**Example pattern** (from `modules/llm.nix`): +```nix +{ + imports = [ + ./dev.nix # System-level dependency + inputs.home-manager.nixosModules.home-manager + ]; + + home-manager.users.christian = { + imports = [ ./home/llm.nix ]; # User-level module + }; +} +``` + +### Host Configuration Structure + +Each host imports: +- `hardware-configuration.nix` (auto-generated, do not edit manually) +- `modules/common.nix` (base system configuration) +- Additional feature modules as needed (`modules/dev.nix`, `modules/llm.nix`) + +**Desktop** (`hosts/desktop/configuration.nix`): +- Imports: `common.nix`, `llm.nix` +- AMD GPU configuration for ROCm/Ollama +- Wireless via iwd +- ROCm acceleration for local LLMs with RX 6800 GPU + +**Laptop** (`hosts/laptop/configuration.nix`): +- Imports: `common.nix`, `dev.nix` +- Laptop-specific: backlight control (`programs.light`), battery alias +- Wireless via iwd +- keyd for capslock → ctrl/esc overlay + +**Hyper-V** (`hosts/hyper-v/configuration.nix`): +- Minimal configuration for virtual machine + +### Common Base Configuration + +`modules/common.nix` provides: +- home-manager integration with global packages and backup handling +- XMonad window manager with xmobar +- Core packages: git, wget, alacritty, dmenu, mosh +- Docker virtualization +- nix-index-database with comma tool +- User "christian" with wheel, video, render, docker groups + +### User Home Configuration + +`modules/home/christian.nix` (imported by common.nix): +- Neovim configuration via `./nvim` +- Custom dmenu with config override +- Alacritty terminal (font size 8) +- Git configuration (Christian, thechristiansoltermann@gmail.com) +- direnv with nix-direnv integration +- Firefox with uBlock Origin extension +- xmobar configuration + +### Feature Modules + +**dev.nix** (system + user): +- Enables `nix-ld` for running non-NixOS binaries +- User modules: VSCode with FHS environment, Claude Code, uv Python package manager +- Adds `~/.local/bin` to PATH + +**llm.nix** (system + user): +- Extends dev.nix (inherits all dev features) +- User module adds Continue VSCode extension with Ollama proxy config +- Desktop host configures Ollama service with ROCm acceleration + +## Special Configurations + +### AMD ROCm for Local LLMs (Desktop Only) + +The desktop uses unstable nixpkgs for Ollama with specific ROCm configuration for the RX 6800 GPU: +- `rocmOverrideGfx = "10.3.0"` for RDNA 2 architecture +- Environment variables to target discrete GPU only (`HIP_VISIBLE_DEVICES = "0"`) +- `HSA_ENABLE_SDMA = "0"` for stability with large models (26B+) + +### Window Manager (XMonad) + +XMonad configuration is in `modules/xmonad.hs`: +- Mod key: Alt (mod1Mask) +- Layouts: Tall, Mirror Tall, Full (all avoiding xmobar struts) +- Focused border: #4eb4fa +- Restart binding: Mod+Q +- Status bar: xmobar via `mySB` integration + +### Unstable Packages + +Desktop uses a separate unstable pkgs overlay for newer packages (currently Ollama): +```nix +let + unstable = import inputs.nixpkgs-unstable { + system = "x86_64-linux"; + config.allowUnfree = true; + config.rocmSupport = true; + }; +in +``` + +## Flake Inputs + +- `nixpkgs`: NixOS 25.11 stable +- `nixpkgs-unstable`: Rolling release for bleeding-edge packages +- `home-manager`: Release 25.11, follows nixpkgs +- `nix-index-database`: For command-not-found functionality +- `nur`: Nix User Repository (used for Firefox extensions) + +## Important Conventions + +1. **Always use the two-layer pattern** when creating new feature modules +2. **System-level modules** import home-manager and specify user imports +3. **User-level modules** contain pure home-manager configuration +4. **Hardware configuration files** are auto-generated - do not manually edit +5. **Use unstable overlay** when you need bleeding-edge versions of specific packages +6. **Test changes** with `nixos-rebuild switch` before committing +7. **Format code** with nixfmt before committing -- cgit v1.2.3