nix/CLAUDE.md

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 repository managing both system configurations (NixOS) and user environments (home-manager). The repository follows a modular architecture with separate host configurations for physical machines, VMs, and standalone home-manager setups.

Essential Commands

Building and Testing

# Build a NixOS system configuration
nix build -L '.#nixosConfigurations.<hostname>.config.system.build.toplevel'

# Build and run a VM with disko
nix build -L '.#nixosConfigurations.vm.config.system.build.vmWithDisko'
./result/bin/disko-vm

# Build home-manager configuration
nix build -L '.#homeConfigurations.work.activationPackage'

# Build the custom neovim package
nix build -L '.#nvim.packages.x86_64-linux.nvim'

Development

# Update flake inputs
nix flake update

# Check flake for errors
nix flake check

# Show flake outputs
nix flake show

# Enter development shell for neovim
cd dots/.config/nvim && nix develop

Architecture

Repository Structure

The repository is organized into distinct layers:

• flake.nix: Root flake defining inputs and outputs. Uses utils.dirNames to automatically discover host directories.
• hosts/: NixOS system configurations (andromache, astyanax, vm). Each host has its own directory with default.nix and hardware configuration.
• home/: home-manager configurations, split into hosts/ (per-host configs) and modules/ (reusable user-level modules).
• modules/: Reusable NixOS modules for system-level configuration (audio, networking, fonts, etc.).
• dots/: Dotfiles and configurations, including a complete neovim flake at dots/.config/nvim/.
• utils/: Helper functions like dirNames for discovering directories.

Key Architectural Patterns

Host Discovery: The flake uses lib.genAttrs hostDirNames to automatically generate nixosConfigurations from directories in hosts/. Adding a new host only requires creating a directory with a default.nix.

Secrets Management: Uses sops-nix with age encryption. Secrets are stored in a separate private repository (nix-secrets) referenced as a flake input. The modules/secrets/default.nix module provides options and templates for injecting secrets into configurations.

Disk Management: Uses disko for declarative disk partitioning. The modules/disko.zfs-encrypted-root.nix module provides a reusable ZFS-on-root setup with encryption, taking a device parameter.

Neovim as Flake: The neovim configuration at dots/.config/nvim/ is a standalone flake using nixCats. It's referenced as a flake input in the root and included in system packages. This allows independent development and version control.

Home Manager Integration: Each NixOS host can include home-manager configuration through home-manager.users.<username>, which imports from home/hosts/<hostname>. Standalone home-manager configurations (like work) are also available for non-NixOS systems.

Module Parameterization: Modules like networking.nix and secrets/default.nix accept parameters and expose options, making them reusable across hosts with different settings.

Input Dependencies

• nixpkgs: Main package source (nixos-unstable)
• nixos-hardware: Hardware-specific configurations
• disko: Declarative disk partitioning
• sops-nix: Secrets management with age/sops
• nix-secrets: Private repository with encrypted secrets (git+ssh)
• home-manager: User environment management
• nixgl: OpenGL wrapper for non-NixOS systems
• firefox-addons: Firefox extension packages
• nvim: Local flake at dots/.config/nvim/

Working with Hosts

Adding a New NixOS Host

1. Create a new directory in hosts/<hostname>/
2. Add default.nix with imports and host-specific configuration
3. Add hard.nix for hardware configuration (generated by nixos-generate-config)
4. The host will automatically be discovered by the flake

Adding a New Home Manager Host

1. Create directory in home/hosts/<hostname>/
2. Add default.nix importing desired modules from home/modules/
3. For standalone (non-NixOS) configs, add entry to homeConfigurations in root flake.nix

Secrets Workflow

Secrets are managed with sops-nix and stored in the private nix-secrets repository:

1. Secrets are encrypted with age using keys at ~/.config/sops/age/keys.txt
2. The modules/secrets/default.nix module reads from ${nix-secrets}/secrets.yaml
3. Secrets are exposed as files in /run/secrets/ with proper ownership
4. Templates can combine multiple secrets (see taskwarrior sync configuration)

Common Patterns

Import Patterns

Modules use different import patterns based on their needs:

# Simple module (no parameters)
imports = [ ../../modules/audio.nix ];

# Parameterized module (function call)
imports = [ (import ../../modules/networking.nix { hostName = "andromache"; }) ];

# Module with all parameters
imports = [
  (import ../../modules/secrets {
    inherit lib inputs config;
  })
];

Special Args

• inputs: Flake inputs, passed as specialArgs to NixOS and extraSpecialArgs to home-manager
• lib, config, pkgs: Standard NixOS/home-manager module arguments

Username Handling

Each host defines a username variable (either "h" or "hektor") used for:

• User creation in NixOS
• Home directory paths
• Secrets ownership
• Home-manager configuration