136 lines
5.5 KiB
Markdown
136 lines
5.5 KiB
Markdown
# 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 for managing multiple machines (gunter, magicman). It uses home-manager for user configurations and sops-nix for secrets management. Custom packages from private git repositories are integrated via flake inputs and overlays.
|
|
|
|
## Essential Commands
|
|
|
|
### Formatting
|
|
```bash
|
|
nix fmt # Format all Nix files (uses nixfmt-tree)
|
|
nix fmt . # Same as above
|
|
```
|
|
|
|
### Building & Testing
|
|
```bash
|
|
# Test build a specific host configuration
|
|
nix build .#nixosConfigurations.gunter.config.system.build.toplevel
|
|
nix build .#nixosConfigurations.magicman.config.system.build.toplevel
|
|
|
|
# Enter development shell (includes act, actionlint, yamllint)
|
|
nix develop
|
|
```
|
|
|
|
If config clearly only affects one host, bulding for just the relevant host is enough.
|
|
Otherwise, build both.
|
|
|
|
### Common Operations
|
|
```bash
|
|
# Check flake without building
|
|
nix flake check
|
|
|
|
# Show flake outputs
|
|
nix flake show
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Flake Structure
|
|
- **Inputs**: Uses both stable (nixos-25.05) and unstable nixpkgs channels
|
|
- **Overlays**: `overlay-stable` provides `pkgs.stable` for stable packages; custom overlays integrate private packages (ghettoptt, huecli, nixprstatus, natstonotify, nix-packages)
|
|
- **System**: x86_64-linux primary, with multi-platform devShell support
|
|
|
|
### Directory Organization
|
|
```
|
|
├── flake.nix # Main entrypoint with overlays and host definitions
|
|
├── hosts/ # Per-host system configurations
|
|
│ ├── gunter/ # Desktop with multi-monitor, nvidia, steam
|
|
│ └── magicman/ # Laptop configuration
|
|
├── home/ # Home-manager user configurations
|
|
│ ├── hosts/ # Per-host user settings (imports packages + programs)
|
|
│ ├── editor/ # Neovim configuration
|
|
│ ├── hyprland/ # Wayland compositor with custom options
|
|
│ ├── packages/ # Simple packages (no options)
|
|
│ ├── programs/ # Programs with home-manager options (dunst, git, firefox, etc.)
|
|
│ ├── services/ # User services (backup, ghettoptt, natstonotify)
|
|
│ ├── scripts/ # User scripts
|
|
│ ├── sops/ # User secrets configuration
|
|
│ ├── ssh/ # SSH configuration
|
|
│ └── zsh/ # Shell configuration
|
|
├── system/ # Shared system-level modules
|
|
│ ├── monitoring/ # logs.nix, metrics.nix
|
|
│ ├── fonts.nix # Font configuration
|
|
│ ├── locale.nix # Localization settings
|
|
│ ├── users.nix # User account definitions
|
|
│ └── ... # Other system modules
|
|
└── secrets/ # SOPS-encrypted secrets (don't modify)
|
|
```
|
|
|
|
### Configuration Pattern
|
|
- Each host's `default.nix` imports: `configuration.nix`, `hardware-configuration.nix`, host-specific modules, `../../system`, and `../../home/hosts/<hostname>`
|
|
- Home-manager imports are in `home/hosts/<hostname>/default.nix` which imports editor, hyprland, packages, programs, services, etc.
|
|
- Shared system config goes in `system/`, host-specific overrides in `hosts/<hostname>/`
|
|
|
|
### Hyprland Custom Options
|
|
The hyprland module in `home/hyprland/default.nix` provides custom options:
|
|
- `hyprland.monitors`: List of monitor configurations
|
|
- `hyprland.extraEnv`: Environment variables
|
|
- `hyprland.extraKeybinds`: Additional keybindings
|
|
- `hyprland.extraWorkspaces`: Named workspace definitions
|
|
- `hyprland.monitorVariables`: Monitor name variables (e.g., `$mon_left`)
|
|
- `hyprland.enableGrimblast`, `hyprland.enableWacom`, `hyprland.cursorNoHardware`: Feature flags
|
|
|
|
## Critical Workflow Rules
|
|
|
|
### Git Tracking for New Files
|
|
**CRITICAL**: Nix flakes ignore untracked files. When adding new files, run `git add <newfile>` BEFORE attempting to build. Builds will fail with "file not found" errors until files are git-tracked.
|
|
|
|
### Branching
|
|
Always create a new branch for changes. Never work directly on master branch.
|
|
|
|
### Formatting
|
|
Always run `nix fmt` before committing. Formatted Nix code is required.
|
|
|
|
### Commit Messages
|
|
Format: `topic: description`
|
|
|
|
Examples:
|
|
- `hyprland: convert deprecated windowrules`
|
|
- `packages: nixfmt-rfc-style renamed`
|
|
- `gunter: use beta nvidia driver`
|
|
|
|
Keep summaries concise. Only add commit body if needed for context.
|
|
|
|
### Forbidden Operations
|
|
- Don't run `nix flake update` (user manages input updates)
|
|
- Don't edit files in `secrets/` directory
|
|
- Don't modify `.sops.yaml`
|
|
- Don't use `nix-shell` (use `nix develop` instead)
|
|
- Don't mix stable/unstable packages arbitrarily
|
|
- Don't skip builds after configuration changes
|
|
|
|
### Adding Programs
|
|
- If no NixOS/home-manager options needed: add to `home/packages`
|
|
- If using options: create subdirectory in `home/programs/`
|
|
- Remember to `git add` new files before building
|
|
|
|
## Package Management
|
|
|
|
### Using Stable Packages
|
|
The `overlay-stable` provides access to stable nixpkgs via `pkgs.stable`:
|
|
```nix
|
|
environment.systemPackages = [ pkgs.stable.somePackage ];
|
|
```
|
|
Do not use packages from stable unless explicitly requested.
|
|
|
|
### Custom Packages
|
|
Custom packages from private repos are available via overlays:
|
|
- `pkgs.ghettoptt`
|
|
- `pkgs.huecli`
|
|
- `pkgs.nixprstatus`
|
|
- `pkgs.natstonotify`
|
|
- Plus packages from `nix-packages` overlay
|