nix/CLAUDE.md

CLAUDE.md

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

Architecture

This is a unified NixOS and Home Manager configuration using the trivionomicon doctrine system as a git subtree.

Directory Structure

• home/ - Home Manager user configuration
  • modules/ - User-level feature modules (terminal, neovim, firefox, ai, etc.)
  • platforms/ - User-specific configs per host (fabian@t14, fabian@posixlycorrect, fabian@vps)
• sys/ - NixOS system configuration
  • modules/ - System-level feature modules (audio, graphics, networking, etc.)
  • platforms/ - Machine-specific configs (t14, posixlycorrect, vps)
• pkgs/ - Custom package overlays and nixpkgs configuration
• trivionomicon/ - Shared doctrine framework (git subtree)
  • doctrine/ - Core library (mkModule, mkSystemFlake)
  • modules/ - Shared modules usable by any host

Namespace Conventions

• config.local.* - Home Manager modules (user level)
• config.local.sys.* - NixOS modules (system level)
• config.trivium.* - Trivionomicon shared modules

Module Patterns

Simple module (single layer):

{config, lib, pkgs, ...}:
with lib; let
  cfg = config.local.programs.terminal;
in {
  options.local.programs.terminal = { enable = mkEnableOption "..."; };
  config = mkIf cfg.enable { ... };
}

Platform Configuration

Each host has paired directories:

• sys/platforms/{hostname}/ - Machine-specific NixOS config
• home/platforms/{user}@{hostname}/ - User-specific Home Manager config

The flake.nix uses trivionomicon.lib.mkSystemFlake to auto-generate configurations from these platform directories.

Trivionomicon System

The trivionomicon is a shared NixOS/Home Manager module framework maintained collaboratively. It lives as a git subtree at trivionomicon/ and provides unified modules that work across both NixOS and Home Manager contexts.

Core Functions

• mkDoctrine - Creates namespace context with the "trivium" prefix and hm/sys awareness
• mkModule - Composes hm.nix + sys.nix + options.nix into a unified module
• mkSystemFlake - Auto-generates flake outputs from platform directories

Module Structure

moduleName/
├── default.nix    # Entry: calls doctrine.lib.mkModule
├── options.nix    # Options split by hm/sys keys
├── hm.nix         # Home Manager implementation (optional)
└── sys.nix        # NixOS implementation (optional)

Available Modules

Modules are located at trivionomicon/modules.

Git Subtree Workflow

Commit separation (critical):

Never create commits that include both:

• Changes inside trivionomicon/
• Changes outside trivionomicon/ (home/, sys/, pkgs/, flake.nix, etc.)

The trivionomicon is a shared project. Each commit touching trivionomicon/ must contain only trivionomicon changes so it can be cleanly pushed upstream.

Commit message conventions:

• If a module was modified: trivionomicon/modules/<module name>: one line summary of changes

Similar layout if something other than a module was modified.

Sync changes with the shared repository:

# Pull updates
git subtree pull --prefix=trivionomicon forgejo@git.posixlycorrect.com:deepState/trivionomicon.git master

# Push changes back
git subtree push --prefix=trivionomicon forgejo@git.posixlycorrect.com:deepState/trivionomicon.git master

Key Files

• pkgs/config/unfree.nix - Allowlist for unfree packages (add packages here when needed)
• pkgs/default.nix - Package overlays and overrides
• trivionomicon/doctrine/lib/ - Core doctrine functions for module composition

Restrictions

Never use any nix, home-manager, nixos-rebuild or nix-collect-garbage commands. Ask before using any git commands.