nixos/GEMINI.md

HakaseOS - NixOS Configuration

This is a modular, flake-based NixOS configuration for a single host (hakase). It features a custom Hyprland desktop environment, automated theming via Matugen, and strict separation of concerns using a custom myConfig object.

Project Structure

• flake.nix: The entry point. Defines inputs (Hyprland, Chaotic, Home Manager, etc.) and creates the system configuration.
• config.nix: Central source of truth. Defines global variables (user details, monitor config, theme settings) exposed as myConfig.
• hosts/hakase/: Host-specific configuration.
  • configuration.nix: Main system entry point.
• modules/: Reusable modules.
  • nixos/: System-level modules (boot, hardware, services).
  • home/: Home-manager modules (UI, apps, user services).
• apps/: Application-specific configurations. Each app has its own directory (e.g., hyprland, firefox, ghostty) with a default.nix.
• assets/: Static assets like wallpapers (firewatch.png).
• secrets/: Encrypted secrets managed by SOPS.

Architecture & Conventions

1. The myConfig Object

Global configuration is not hardcoded in modules. Instead, it is defined in config.nix and passed to all modules via specialArgs. Usage Pattern:

# In any module
{ pkgs, config, myConfig, ... }:
{
  # Access values
  home.username = myConfig.nixos.username;
}

2. Module Hierarchy

• System: flake.nix -> hosts/hakase/configuration.nix -> modules/nixos/default.nix -> modules/nixos/*.nix
• User: modules/nixos/user.nix (or similar) -> home-manager -> home/hakase.nix -> modules/home/*.nix -> apps/*/default.nix

3. Application Configuration

Do not dump config into one large file. Create a dedicated folder in apps/<app_name>/ with a default.nix.

• Example: apps/ghostty/default.nix

Key Commands

System Management

• Rebuild & Switch:

  sudo nixos-rebuild switch --flake ~/.config/nixos/#hakase
  # or alias:
  update
  

Secrets (SOPS)

• Edit Secrets:

  nix-shell -p sops --run "sops secrets/secrets.yaml"
  

• Update Keys:

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

Development Guidelines

• Matugen: used for theming. Templates are located in apps/matugen/templates/.
• Hyprland: Config is split into apps/hyprland/hypr/*.nix.
• Formatting: Follow existing indentation (2 spaces usually).
• Commits: Use Conventional Commits (e.g., feat(hyprland): add new bind).