From 890767d22426b98211d2fd8ec189f88ae3c78f44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Wed, 18 Feb 2026 01:50:30 +0100 Subject: [PATCH] Add CLAUDE.md with project documentation Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..105ec4a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,87 @@ +# CLAUDE.md + +NixOS + nix-darwin dotfiles managing multiple hosts via a single flake. +Uses **flake-parts**, **import-tree**, **home-manager**, and **agenix** for secrets. + +## Hosts + +| Host | Platform | Role | +|------|----------|------| +| **endurance** | nixos (x86_64-linux) | Desktop workstation (AMD GPU, Niri compositor) | +| **aepplet** | nixos (x86_64-linux) | Data/compute server | +| **vasa** | darwin (x86_64-darwin) | macOS (minimal config) | + +Host configs live in `hosts/{name}/` with `default.nix`, `hardware.nix`, and `disko.nix`. + +## Key directories + +| Path | What's there | +|------|-------------| +| `flake.nix` | Entry point — all inputs and flake-parts imports | +| `modules/flake/` | Flake-parts modules: host definitions, home-manager wiring, packages, formatter, lib | +| `modules/generic/` | Shared config (nix settings, profiles, base packages) — applies to all platforms | +| `modules/nixos/` | NixOS-specific: system, users, SSH, services (ollama, traefik, beszel, metrics) | +| `modules/nixos/profiles/` | Composable feature profiles: `graphical`, `docker`, `work` | +| `modules/darwin/` | macOS-specific modules | +| `modules/home/` | Home-manager modules shared across hosts (helix, terminal, shell, kitty, GUI) | +| `home/by-host/{name}/` | Per-host home-manager config (programs, services, theming) | +| `home/by-host/{name}/config/` | Auto-imported config modules (dev, shell, git, etc.) | +| `home/by-host/{name}/misc/` | Optional per-host services (launcher, browser, recording) | +| `home/by-host/{name}/niri/` | Niri WM config (keybinds, window rules, autostart) | +| `packages/` | Custom packages (each dir has `package.nix`, auto-discovered) | +| `overlays/` | Nixpkgs overlays (lix, unstable channel packages, custom builds) | +| `secrets/` | Age-encrypted secrets managed by agenix | + +## Custom options namespace + +This flake uses a `bosun` namespace for composable options: + +```nix +bosun.profiles.graphical.enable = true; +bosun.profiles.docker.enable = true; +bosun.profiles.work.enable = true; +bosun.key = "ssh-ed25519 ..."; # Host SSH public key +bosun.secrets.npmrc = { ... }; # Secret definitions +``` + +Profile definitions are in `modules/generic/profiles.nix`, implementations in `modules/nixos/profiles/`. + +## Architecture patterns + +- **import-tree** auto-discovers and imports `.nix` files in `modules/flake/`. Files prefixed with `_` are excluded from auto-import. +- **easy-hosts** manages host definitions in `modules/flake/hosts.nix`. +- **Overlays** receive `inputs` and `channels` (multiple nixpkgs instances) via the `withChannels` wrapper in `overlays/default.nix`. +- **Stylix** handles system-wide theming (colors, fonts) from a single config. +- **Lix** is used instead of stock Nix. + +## Commands (`just`) + +``` +just deploy # nixos-rebuild switch / darwin-rebuild switch +just debug # Build with --show-trace --verbose via nom +just repl # nix repl with flake loaded +just shell # Enter a dev shell +just up # Update all flake inputs +just upp # Update a single input +just gc # Garbage collect old generations +just rekey # Rekey all agenix secrets +just edit-secret # Edit an encrypted secret +``` + +## Where to find settings + +| Looking for... | Go to | +|---------------|-------| +| Which hosts exist and their platform | `modules/flake/hosts.nix` | +| Home-manager host assignments | `modules/flake/homes.nix` | +| Nix daemon settings, substituters, gc | `modules/generic/nix.nix` | +| Locale, timezone, stateVersion | `modules/nixos/system.nix` | +| User accounts | `modules/nixos/users.nix` | +| SSH daemon config | `modules/nixos/ssh.nix` | +| Shell config (Fish, Nushell) | `modules/home/common/terminal/shell/` | +| Helix editor config | `modules/home/common/helix/` | +| Kitty terminal | `modules/home/gui/kitty.nix` | +| Desktop programs for endurance | `home/by-host/endurance/config/dev.nix` and `misc/` | +| Niri keybinds & window rules | `home/by-host/endurance/niri/` | +| Available packages | `packages/` (auto-discovered by flake-parts) | +| Secret definitions | `modules/*/secrets.nix` + `secrets/*.age` |