CLAUDE.md

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

Build Commands

# Rebuild and switch to new configuration (desktop x86_64)
sudo nixos-rebuild switch --flake ~/.config/nixos/#hakase

# Rebuild MacBook configuration (aarch64)
sudo nixos-rebuild switch --flake ~/.config/nixos/#macbook

# Dry-run build to check for errors without applying
sudo nixos-rebuild build --flake ~/.config/nixos/#hakase

# Manage SOPS secrets
nix-shell -p sops --run "sops secrets/secrets.yaml"
nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"

Architecture Overview

This is a modular, flake-based NixOS configuration supporting two hosts: hakase (x86_64 desktop) and macbook (aarch64 Apple Silicon).

Key Entry Points

flake.nix - Declares inputs and creates both NixOS configurations (hakase, macbook)
config.nix - Central configuration values separated by host (hakase, macbook keys)
hosts/{hakase,macbook}/configuration.nix - Host-level entry points importing system modules
home/hakase.nix - Home Manager entry point for user environment (referenced from flake)

Module Organization

Three-tier system:

System modules (modules/nixos/) - NixOS-level settings (boot, kernel, services, hardware)
Home Manager modules (modules/home/) - User-level environment and applications
Application configs (apps/) - Per-application configuration directories with default.nix files

Examples:

apps/hyprland/default.nix + apps/hyprland/hypr/*.nix - Hyprland compositor config
apps/firefox/default.nix - Browser with bookmarks and theming
apps/ghostty/default.nix - Terminal emulator
apps/neovim/default.nix - Editor (via nixovim external flake)

Configuration Flow

flake.nix (outputs)
  ├─ hakase (x86_64-linux)
  │   ├─ hosts/hakase/configuration.nix
  │   │   └─ modules/nixos/default.nix (imports system modules)
  │   └─ home-manager
  │       └─ home/hakase.nix
  │           └─ modules/home/* (imports Home Manager modules)
  │               └─ apps/* (application configurations)
  │
  └─ macbook (aarch64-linux)
      ├─ hosts/macbook/configuration.nix
      │   └─ modules/nixos/default.nix
      └─ Similar home-manager structure

config.nix provides myConfig via specialArgs to both configurations

Configuration Structure (config.nix)

The config.nix file defines host-specific configuration under hakase and macbook keys. Common values include:

myConfig = {
  nixos = { username, hostname, timezone }
  git = { username, email, defaultBranch }
  theme = { mode }  # "dark" or "light"
  terminal = { default, font, aliases }
  font = { monospace, monospaceScript, sans }
  hyprland = { monitors, wallpaper, kb_options }
  firefox = { bookmarks, newtabpage }
  # ... more app-specific configs
}

To add a host-specific override, define it in the host's myConfig section in config.nix. The flake passes allConfig.{hostname} as specialArgs, so modules access the correct host configuration.

Module Pattern

Modules receive standard NixOS parameters plus custom ones:

{ pkgs, config, lib, myConfig, inputs, system, ... }:

Key patterns:

Access host config: myConfig.nixos.username, myConfig.terminal.default
Use host-specific packages: pkgs.unstable (from nixpkgs), inputs.neovim (from flake inputs)
Reference other modules via config (e.g., config.home.homeDirectory)
Conditional logic: Check system or myConfig values

Secrets Management

SOPS-encrypted secrets stored in secrets/secrets.yaml. Age key at ~/.config/sops/age/keys.txt.

In modules, reference secrets via:

config.sops.secrets.secret_name.path

Key Technologies

Hyprland with UWSM (systemd user session management)
Matugen for automatic system-wide theming from wallpaper colors
Home Manager for user environment and program configuration
nixovim external flake for Neovim configuration (treesitter disabled due to read-only NixOS constraints)
SOPS-Nix for secrets encryption
CachyOS kernel on hakase (x86_64), Asahi Linux on macbook (aarch64)

Git Commit Convention

Use conventional commits with scope: feat(scope):, fix(scope):, refactor:, add:, remove:, cleanup:

Common scopes: nixos, home, apps, config, modules, hyprland, firefox, etc.

4.4 KiB Raw Blame History