@@ -5,6 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
55## Core Commands
66
77### macOS (nix-darwin)
8+
89``` bash
910# Apply system configuration (auto-detects hostname)
1011nixswitch
@@ -17,6 +18,7 @@ git pull && nixswitch
1718```
1819
1920### Linux (Home Manager)
21+
2022``` bash
2123# Apply generic Linux configuration (minimal - for Docker/containers)
2224hmswitch
@@ -40,12 +42,14 @@ git pull && hmswitch
4042This is a ** cross-platform Nix configuration** managing both macOS hosts and Linux development environments. The architecture follows a modular, hybrid approach:
4143
4244### Key Design Principles
45+
4346- ** Host-VM separation** : Clean macOS host with isolated Linux development environment
4447- ** ARM64-first** : Optimized for Apple Silicon and ARM cloud instances
4548- ** Shared configuration** : Common settings abstracted into reusable modules
4649- ** Hybrid package management** : Nix for development tools, Homebrew for macOS GUI apps
4750
4851### Directory Structure
52+
4953```
5054├── flake.nix # Main orchestrator - defines all configurations
5155├── common/ # Shared configuration across platforms
@@ -78,6 +82,7 @@ This is a **cross-platform Nix configuration** managing both macOS hosts and Lin
7882```
7983
8084### Configuration Flow
85+
81861 . ** flake.nix** - Entry point defining ` darwinConfigurations ` and ` homeConfigurations `
82872 . ** common/home-manager-base.nix** - Imports shared modules (home-packages, claude-code, programs, scripts)
83883 . ** common/programs/default.nix** - Centralized program configurations (direnv, gh, zsh base)
@@ -86,7 +91,9 @@ This is a **cross-platform Nix configuration** managing both macOS hosts and Lin
86916 . ** packages.nix** - Centralized package definitions organized by category
8792
8893### Recent Architectural Changes (2025)
94+
8995** Major refactoring eliminated 479+ lines of duplicate configuration:**
96+
9097- Created ` common/home-manager-base.nix ` to centralize Home Manager settings
9198- Created ` common/programs/default.nix ` for shared program configurations
9299- ** Unified git configuration** in ` common/git/ ` with platform detection for SSH signing
@@ -100,6 +107,7 @@ This is a **cross-platform Nix configuration** managing both macOS hosts and Lin
100107## Development Workflow
101108
102109### Making Configuration Changes
110+
1031111 . Edit configuration files in appropriate directory:
104112 - ` common/ ` for shared changes
105113 - ` common/profiles/ ` for optional profiles (Wayland, etc.)
@@ -109,6 +117,7 @@ This is a **cross-platform Nix configuration** managing both macOS hosts and Lin
1091173 . Commit changes: ` git commit -am "description" `
110118
111119### Package Management
120+
112121- ** Add everywhere** : Edit ` common/packages.nix ` :
113122 - ` corePackages ` - Essential CLI tools (oh-my-posh, eza, zoxide, bat, etc.)
114123 - ` devPackages ` - Development tools (gh, lazygit, docker-compose, htop, curl, wget, etc.)
@@ -118,6 +127,7 @@ This is a **cross-platform Nix configuration** managing both macOS hosts and Lin
118127- ** Profile-specific packages** : Edit ` common/profiles/hyprland.nix ` for Linux desktop apps
119128
120129** IMPORTANT** : Platform-specific packages must be separated:
130+
121131- macOS-only packages (like ` reattach-to-user-namespace ` ) go in ` darwinPackages ` and are imported via ` systems/aarch64-darwin/home.nix `
122132- Profile-specific packages (like Hyprland/Wayland tools) go in ` common/profiles/hyprland.nix ` and are opt-in via ` extraModules `
123133- Never put macOS-only packages in shared ` corePackages ` or ` devPackages ` or they'll break Linux builds
@@ -128,9 +138,11 @@ This is a **cross-platform Nix configuration** managing both macOS hosts and Lin
128138** Profile Architecture** : Optional configurations that extend the base system without polluting minimal environments.
129139
130140** Available Profiles** :
141+
131142- ` common/profiles/hyprland.nix ` - Hyprland desktop environment (full-featured, Linux only)
132143
133144** hyprland.nix includes** :
145+
134146- ** Hyprland** - Modern Wayland compositor with animations
135147- ** Dev tools** - mise, lazydocker, btop, Docker, databases
136148- ** Desktop apps** - Obsidian, Signal, Chromium, LocalSend
@@ -156,6 +168,7 @@ desktop = mkHomeManagerConfig {
156168
157169** Customizing hyprland.nix** :
158170Edit the profile and comment out packages you don't want:
171+
159172``` nix
160173# Media (comment out what you don't want)
161174mpv
@@ -166,13 +179,16 @@ spotify
166179```
167180
168181** Benefits** :
182+
169183- Default stays minimal (Docker/containers unaffected)
170184- Explicit opt-in for additional functionality
171185- Easy to compose multiple profiles
172186- Clear separation of concerns
173187
174188### Adding New Hosts
189+
175190Create new configuration in ` flake.nix ` :
191+
176192``` nix
177193# For macOS
178194"hostname" = mkDarwinSystem {
@@ -189,22 +205,27 @@ Create new configuration in `flake.nix`:
189205## Special Features
190206
191207### Claude Code Integration
208+
192209Located in ` common/claude-code/ ` , this provides:
210+
193211- ** Custom commands** : Linear integration, conventional commits, breakdown command
194212- ** Sophisticated hooks** : Automated linting and quality checks
195213- ** Modular structure** : Combines local and remote commands via symlinkJoin
196214
197215### Shell Configuration
216+
198217- ** History Search** : fzf with Catppuccin Mocha theme (` source <(fzf --zsh) ` )
199218- ** Directory Navigation** : zoxide aliased to ` cd ` for smart directory jumping
200219- ** Prompt** : Oh My Posh with custom theme
201220- ** Completions** : Carapace for 300+ CLI tools
202221
203222### Version Management
223+
204224- ** Terraform** : Managed as regular nixpkgs in Linux configurations
205225- ** Node.js** : Uses nodePackages.pnpm from nixpkgs
206226
207227### Multi-Environment Support
228+
208229- ** Generic Linux** : Flexible Home Manager configuration for any Linux environment (minimal by default)
209230- ** Profile-based configs** : Optional modules for desktop environments (Wayland/Sway), server tools, etc.
210231- ** Development Shell** : Available via ` nix develop ` for working on this configuration
@@ -213,12 +234,14 @@ Located in `common/claude-code/`, this provides:
213234## Platform-Specific Notes
214235
215236### macOS (nix-darwin)
237+
216238- Manages system preferences via ` systems/aarch64-darwin/defaults.nix `
217239- Dock configuration in ` systems/aarch64-darwin/dock.nix `
218240- Homebrew integration for GUI applications
219241- SSH configuration for VM connectivity
220242
221243### Linux (home-manager)
244+
222245- ** Minimal by default** - base configuration for Docker/containers
223246- ** Profile system** - opt-in desktop environments (Wayland/Sway) or additional tools
224247- Docker integration (docker-compose package)
@@ -227,10 +250,12 @@ Located in `common/claude-code/`, this provides:
227250- Auto-optimise-store enabled (better suited for Linux than macOS)
228251
229252** Available Configurations** :
253+
230254- ` #minimal-x86 ` / ` #minimal-arm ` - Minimal (Docker/containers)
231255- ` #desktop-x86 ` / ` #desktop-arm ` - Full desktop environment (Hyprland, dev tools, GUI apps)
232256
233257## Security Considerations
258+
234259- SSH keys managed through 1Password integration
235260- Tailscale for secure cloud connectivity
236261- Proper credential management for AWS profiles
@@ -255,6 +280,7 @@ docker-compose run --rm nix-dev
255280```
256281
257282** Docker Setup Details:**
283+
258284- Ubuntu 24.04 base with pinned SHA256
259285- Pinned package versions (curl, git, sudo, xz-utils, ca-certificates, zsh)
260286- Pinned Nix version: 2.24.10
@@ -265,6 +291,7 @@ docker-compose run --rm nix-dev
265291## Configuration Development Commands
266292
267293### Nix Development Tools (via ` nix develop ` )
294+
268295``` bash
269296# Enter development shell with Nix tools
270297nix develop
@@ -277,6 +304,7 @@ nil # Nix LSP for editor integration
277304```
278305
279306### Configuration Validation
307+
280308``` bash
281309# Check flake syntax and evaluation
282310nix flake check
@@ -288,6 +316,7 @@ nix eval .#homeConfigurations.ubuntu.activationPackage
288316```
289317
290318### Troubleshooting Commands
319+
291320``` bash
292321# Debug build issues
293322nixswitch --show-trace
@@ -305,6 +334,7 @@ home-manager generations # Linux - shows available generations
305334## Advanced Architecture Details
306335
307336### Module Resolution System
337+
308338The configuration uses a layered import system that eliminates duplication:
309339
3103401 . ** flake.nix** : Orchestrates everything using ` mkDarwinSystem ` and ` mkHomeManagerConfig ` functions
@@ -323,6 +353,7 @@ The configuration uses a layered import system that eliminates duplication:
323353 - ** Linux** : homeDirectory + nix settings + platform aliases (hmswitch, hm-user) + worktree manager
324354
325355### Cross-Platform Module Strategy
356+
326357- ** Shared modules** in ` common/ ` contain ALL cross-platform configuration
327358- ** Platform modules** in ` systems/{arch}/ ` are minimal - only truly platform-specific settings
328359- ** Import chains** :
@@ -331,14 +362,17 @@ The configuration uses a layered import system that eliminates duplication:
331362- ** DRY principle** : Zero duplication between platforms - shared config centralized once
332363
333364### Performance Optimizations
365+
334366Built-in performance tuning throughout:
367+
335368- ** Build parallelization** : ` max-jobs = "auto" ` , ` cores = 0 `
336369- ** Download optimization** : 256MB buffer, 50 HTTP connections
337370- ** Store optimization** : ` nix.optimise.automatic = true ` on macOS only (in ` systems/aarch64-darwin/default.nix ` )
338371 - ** CRITICAL** : Do NOT set ` nix.optimise ` in ` common/default.nix ` - it only works with nix-darwin, not home-manager
339372 - Linux uses standard nix settings without ` optimise.automatic `
340373
341374### State Management Architecture
375+
342376- ** Version pinning** : ` common/versions.nix ` prevents Home Manager version conflicts
343377- ** Hostname detection** : Auto-detects via ` scutil --get LocalHostName ` (macOS)
344378- ** Username validation** : Runtime validation with helpful error messages
@@ -347,6 +381,7 @@ Built-in performance tuning throughout:
347381## Critical Implementation Patterns
348382
349383### Module Import Best Practices
384+
350385``` nix
351386# ✅ Correct: Import with proper parameter passing
352387./common/module.nix
@@ -359,13 +394,16 @@ Built-in performance tuning throughout:
359394```
360395
361396### Configuration Override Hierarchy
397+
3623981 . ** flake.nix** : System-level overrides
3633992 . ** systems/{arch}/default.nix** : Platform-specific overrides
3644003 . ** common/** : Shared defaults
3654014 . ** Individual modules** : Specific functionality
366402
367403### ZSH Configuration Pattern
404+
368405** IMPORTANT** : ZSH configuration uses ` initContent ` (not deprecated ` initExtra ` ):
406+
369407- ** common/programs/default.nix** sets base ` programs.zsh.initContent `
370408- ** Platform configs** can extend with their own ` programs.zsh.initContent ` for platform-specific init
371409- ** Platform aliases** set via ` programs.zsh.shellAliases ` merge with shared aliases from ` common/zsh/shared.nix `
@@ -382,26 +420,31 @@ Built-in performance tuning throughout:
382420 - ` tools ` - Tool initialization (fzf, zoxide, oh-my-posh, carapace)
383421
384422### Error Handling Patterns
423+
385424The codebase implements defensive configuration:
425+
386426- ** Validation functions** : ` validateUsername ` with helpful error messages
387427- ** Fallback options** : ` fallback = true ` in Nix settings
388428- ** Graceful degradation** : Optional features with null checks
389429
390430## Security Architecture
391431
392432### SSH Key Management
433+
393434- ** 1Password integration** : SSH agent socket configuration for seamless key access
394435- ** Per-platform paths** : macOS uses Library/Group Containers path
395436- ** Automatic setup** : System activation scripts configure SSH properly
396437
397438### Credential Isolation
439+
398440- ** Home Manager** : User-level secrets and configurations
399441- ** System-level** : Only essential system packages and settings
400442- ** Cloud integration** : AWS profiles, Tailscale for secure connectivity
401443
402444## Code Quality Standards
403445
404446** 6 Golden Rules for Clean Code** (Neo Kim):
447+
4054481 . ** SOC** - Separation of concerns
4064492 . ** DYC** - Document your code
4074503 . ** DRY** - Don't repeat yourself
@@ -410,6 +453,7 @@ The codebase implements defensive configuration:
4104536 . ** YAGNI** - You ain't gonna need it
411454
412455### Nix-Specific Quality Guidelines
456+
413457- ** Pure functions** : All configuration functions should be deterministic
414458- ** Explicit dependencies** : Always declare inputs explicitly
415459- ** Modular design** : Each .nix file should have single responsibility
0 commit comments