.dotfiles/CLAUDE.md

CLAUDE.md

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

Overview

NixOS dotfiles using Flakes + Home Manager for a single user (jashton) across multiple hosts (thinkpad, desktop, framework). Pinned to nixos-26.05.

Common Commands

# Rebuild and switch the current system (thinkpad)
sudo nixos-rebuild switch --flake ~/.dotfiles#thinkpad

# Check the flake for errors without applying
nix flake check

# Update flake inputs (e.g. nixpkgs, home-manager)
nix flake update

# Open the flake entrypoint in nvim
enix   # alias: nvim ~/.dotfiles/flake.nix

# Open the home-manager user config in nvim
ehome  # alias: nvim ~/.dotfiles/home/jashton.nix

# List registered ports
ports  # alias: cat ~/.dotfiles/ports.registry

Architecture

The repo is structured as a standard Nix Flakes configuration. flake.nix defines nixosConfigurations for each host and wires in Home Manager as a NixOS module. Each host's Home Manager is pointed at a single shared user config (home/jashton.nix).

flake.nix                    # Entrypoint; defines per-host nixosConfigurations
hosts/<host>/default.nix     # Host-specific config (imports hardware.nix + system/)
hosts/<host>/hardware.nix    # nixos-generate-config output (don't manually edit)
system/                      # Shared NixOS system config (all hosts)
  default.nix                # Aggregates: packages, core, network, security, services, virtualisation
  packages.nix               # System-level packages + allowUnfree
  core/                      # Zsh, fonts, nix settings, locale, boot, audio, power
  security/                  # Users, sudo, polkit, TPM2, systemd hardening
  services/                  # Display manager (GDM), Xserver, i3 WM, picom, printing, Bluetooth
  network/                   # Pi-hole config
  virtualisation/            # VM/container support
home/jashton.nix             # Home Manager user config; shared across all hosts
  home/programs/             # Per-program HM config: alacritty, git, nvim
  home/desktop/              # Desktop environment: i3, polybar, rofi, dunst, gnome dconf

Key Design Decisions

• Dual desktop environment: Both GNOME (GDM display manager) and i3 (window manager via Xserver) are configured and co-exist. GNOME extensions are declared via dconf.settings in home/desktop/gnome.nix.
• Shell scripts as Nix packages: Custom scripts (find-open-port, lock-screen, power-menu, weather-cache) are defined inline in home/jashton.nix using pkgs.writeShellScriptBin so they are on $PATH without a separate scripts directory.
• Port registry: ports.registry is a plain-text file tracking assigned dev ports 8000–8999. The find-open-port script appends to it; don't assign ports manually without checking it first.
• Zsh configured at system level: programs.zsh (aliases, Oh My Zsh, history) lives in system/core/env.nix. The ~/.zshrc written by Home Manager is intentionally a stub to suppress the zsh-newuser-install prompt.
• Host hardware files: hosts/thinkpad/hardware.nix is auto-generated by nixos-generate-config. Edits here (e.g. Howdy IR camera path /dev/video66) are intentional overrides — don't regenerate and overwrite.
• stateVersion: Both system.stateVersion and home.stateVersion are set to "26.05". Do not change these.