nixos/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Architecture: Dendritic Pattern

This config uses the den framework with the dendritic pattern — configurations are composed from reusable aspects rather than per-host files.

Key concepts:

• Aspects (den.aspects.<name>) — named, composable feature modules. Each aspect can define nixos (system config) and/or homeManager (user config) blocks.
• Hosts (den.hosts.x86_64-linux.<hostname>) — defined in modules/den.nix, each assigned an aspect that lists its includes.
• import-tree — automatically imports all .nix files under modules/, so adding a new file is enough to register it.
• flake-aspects — wires the den module system into the flake output.

Host→aspect mapping (from modules/den.nix):

• desktop — gaming + dev + creative, Nvidia GPU
• notebook — portable dev + creative, Intel GPU
• work — portable dev only, no gaming/creative

Module layout

modules/
  den.nix          # host declarations and aspect composition
  output.nix       # exposes flake.nixosConfigurations option
  identity.nix     # local.identity options (username, email, SSH key)
  core.nix         # base: nix settings, caches, locale, base packages
  services.nix     # shared system services
  wayland.nix      # Wayland env vars
  niri.nix         # niri compositor + quickshell bar + display tools
  dev.nix          # dev tools, LSPs, Docker, JDKs (system-level)
  portable.nix     # power management, TLP, firewall
  desktop.nix      # desktop-specific hardware/packages
  notebook.nix     # notebook-specific packages
  work.nix         # work-specific packages
  secrets.nix      # sops-nix integration
  _hardware/       # per-host hardware-configuration.nix files
  _home/           # home-manager modules (imported by den.aspects.zoty)
    default.nix    # zsh, direnv, common home packages (firefox, kitty, claude-code)
    niri.nix       # niri home config
    git.nix        # git identity
    theme.nix      # GTK/icon theme
    cursor.nix     # cursor theme
    dolphin.nix    # file manager
    xdg-dirs.nix   # XDG directory overrides
quickshell/        # QML bar widgets (quickshell + qml-niri)

Common commands

just switch              # rebuild + switch (uses current hostname)
just switch desktop      # target a specific host
just build               # build only, don't switch
just test                # apply temporarily (reverts on next boot)
just diff                # show what changed vs running system
just check               # evaluate flake for errors
just update              # update all flake inputs
just update-input nixpkgs  # update a single input
just gc                  # garbage collect (>7 days old)
just repl                # nix repl with flake loaded
just secrets             # edit SOPS-encrypted secrets
just iso                 # build installer ISO

Inputs

Input	Channel	Role
nixpkgs	nixos-25.11	stable packages
nixpkgs-unstable	nixos-unstable	neovim, JDKs, some dev tools
home-manager	release-25.11	user environment
sops-nix	—	secret decryption at boot
niri-flake	—	niri compositor
disko	—	declarative disk partitioning
claude-code	sadjow/claude-code-nix	claude-code CLI
qml-niri	imiric/qml-niri	quickshell niri integration

Secrets (SOPS + age)

• Encrypted in secrets/secrets.yaml, decrypted at boot by sops-nix.
• Age key must exist at /etc/sops/age/keys.txt before first deploy.
• New secrets: add to just secrets, then declare in modules/secrets.nix.
• New host key: add public key to .sops.yaml, then run sops updatekeys secrets/secrets.yaml.

Adding a new host

1. Copy hardware config to modules/_hardware/<hostname>-hardware.nix.
2. Add den.hosts.x86_64-linux.<hostname> in modules/den.nix.
3. Define a den.aspects.<hostname> with the desired includes list.

Identity

Global identity (username, full name, email, SSH key) is declared as NixOS options in modules/identity.nix and passed to home-manager modules via specialArgs. Override local.identity.* options in a host aspect when needed.