60 lines
3.3 KiB
Markdown
60 lines
3.3 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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.
|