78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What This Is
|
|
|
|
Personal NixOS system configuration for host `cesium` — an x86_64 desktop workstation with NVIDIA GPU. Uses NixOS with **Flakes** and Home Manager. NixOS version is locked to 25.11.
|
|
|
|
The project root is `/mnt/data/nixos/`. The actual NixOS configuration lives in the `nixos/` subdirectory and is synced to `/etc/nixos/` via `make sync-etc`, or built directly from `nixos/` via `make rebuild`.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Rebuild from ./nixos directly (no sync to /etc/nixos)
|
|
make rebuild
|
|
|
|
# Rebuild after upgrading flake inputs (updates flake.lock)
|
|
make upgrade
|
|
|
|
# Sync nixos/ to /etc/nixos and rebuild
|
|
make sync-etc
|
|
|
|
# Sync nixos/ to /etc/nixos and upgrade flake inputs
|
|
make upgrade-etc
|
|
|
|
# Dry-run sync to preview file changes
|
|
make sync-etc-dry-run
|
|
|
|
# Validate all .nix files (runs automatically as pre-commit hook)
|
|
make test
|
|
|
|
# Optimize store and garbage collect
|
|
make cleanup
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Entry point is `nixos/flake.nix`, which defines the `cesium` NixOS configuration:
|
|
|
|
```
|
|
nixos/flake.nix # Flake: inputs (nixpkgs 25.11, home-manager, nix-flatpak, unstable)
|
|
nixos/configuration.nix # Top-level: imports all modules, enables Home Manager
|
|
├── hardware-configuration.nix # Auto-generated (gitignored), host hardware
|
|
├── cesium.nix # Host-specific: NVIDIA drivers, hostname, firewall ports
|
|
├── common.nix # System-wide: bootloader, locale, GNOME, PipeWire, packages
|
|
├── mounts.nix # CIFS/SMB mounts to TrueNAS (automount with systemd)
|
|
├── services.nix # Docker (custom data root /home/docker), ddev
|
|
├── users/sebastian.nix # User account, groups, SSH askpass
|
|
├── home.nix # Home Manager: apps, shell, git, scripts, Flatpak
|
|
├── programs.nix # Home Manager: git, shell programs config
|
|
├── dconf.nix # Home Manager: GNOME dconf settings
|
|
├── scripts.nix # Custom shell scripts (composer, lazydocker, gclb)
|
|
├── flakes.nix # Extra flake-based packages (e.g. Hytale launcher)
|
|
├── vm-guest.nix # Optional: SPICE agent for VM clipboard/file sharing
|
|
└── vm-host.nix # Optional: KVM/QEMU host with libvirtd, virt-manager
|
|
```
|
|
|
|
Supporting files in `nixos/config/`:
|
|
- `p10k.zsh` — Powerlevel10k prompt config
|
|
- `zsh-custom.zsh` — Custom zsh configuration
|
|
- `crest_iv_black-cut.jpg` — Wallpaper
|
|
|
|
Key design patterns:
|
|
- `cesium.nix` contains all host-specific hardware config (NVIDIA, hostname, ports)
|
|
- `common.nix` handles system-level config (boot, locale, desktop, audio, auto-updates, GC)
|
|
- `home.nix` handles user-level config via Home Manager (applications, shell, GTK theme, Flatpak)
|
|
- `programs.nix` and `dconf.nix` split out Home Manager programs and GNOME settings
|
|
- `scripts.nix` defines Docker-wrapped CLI tools using `writeShellScriptBin`
|
|
- `mounts.nix` uses systemd automount with 60s idle timeout for TrueNAS SMB shares
|
|
- `vm-guest.nix` and `vm-host.nix` are optional modules (not imported by default)
|
|
- `nixpkgs-unstable` overlay is used selectively (e.g. `rustdesk-flutter`)
|
|
|
|
## Conventions
|
|
|
|
- **Commit messages** use `[TASK]` prefix (e.g., `[TASK] Add filemounts`)
|
|
- **Formatting**: 2-space indentation for `.nix` files, 4-space for everything else (see `.editorconfig`)
|
|
- **Unfree packages** are allowed (`nixpkgs.config.allowUnfree = true`)
|
|
- `hardware-configuration.nix` is gitignored — it's auto-generated per machine |