1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
# 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
### Verify Changes (use this first)
```bash
nix build ~/.config/nixos#nixosConfigurations.$(hostname).config.system.build.toplevel --no-link
```
Use this to catch evaluation and build errors without sudo or activating the system.
### Rebuild System
```bash
sudo nixos-rebuild switch --flake ~/.config/nixos
```
Note: Claude Code cannot run this — it requires sudo. Ask the user to run it.
### Format Nix Files
```bash
nixfmt <file>.nix
```
### Flake Operations
```bash
nix flake update # Update all flake inputs
nix flake lock --update-input <input-name> # 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, [email protected])
- 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. **Verify changes** with `nix build` (see above) before committing
7. **Format code** with nixfmt before committing
7. **Commit messages** should be a single short sentence — no body, no bullet points, no co-author line
|
