Skip to content

AGENTS.md

Latest commit

 

History

History
129 lines (104 loc) · 5.8 KB

AGENTS.md

File metadata and controls

129 lines (104 loc) · 5.8 KB
Raw

The ShizNix

Flake-based NixOS configuration with 4 hosts, home-manager as NixOS module, enable-by-option module system, and system-wide Stylix theming.

Architecture

  • Language: Nix (.nix)
  • Build: Nix flakes (nixos-rebuild switch --flake .#<host>)
  • Formatter: Alejandra (alejandra .)
  • Module pattern: Enable-by-option (options.modules.<cat>.<name>.enable = mkEnableOption; config = mkIf cfg.enable { … };)
  • Home-Manager: Integrated as NixOS module (not standalone) via home-manager.nixosModules.home-manager
  • Theming: Stylix (Monokai Pro Spectrum base16) propagates colors/fonts to apps
  • External configs: external/ git submodules linked via mkOutOfStoreSymlink

Key Directories

Directory Purpose
flake.nix Flake entry — 16 inputs, 4 hosts, overlays, templates, packages
modules/nixos/ System-level modules — 15 categories (see modules/nixos/AGENTS.md)
modules/home-manager/ User-level modules — 7 categories (see modules/home-manager/AGENTS.md)
home/ Per-user home-manager configs — tlh, smg, user (see home/AGENTS.md)
hosts/ Per-host NixOS configs — 4 hosts (see hosts/AGENTS.md)
overlays/ Nixpkgs overlays (see overlays/AGENTS.md)
pkgs/ Custom packages — 8 derivations (see pkgs/AGENTS.md)
external/ Git submodules — awesome, nvim, firefox, base16 scheme (see external/AGENTS.md)
templates/ 42 dev environment flake templates (see templates/AGENTS.md)

Hosts

Host Type User GPU Desktop Kernel
bagalamukhi Lenovo Legion 5 Pro tlh NVIDIA+Intel Prime awesome+LightDM xanmod
matangi Lenovo Legion Pro smg NVIDIA+Intel Prime xfce xanmod
bhairavi VM tlh modesetting awesome xanmod
chhinamasta Live USB ISO user Intel awesome xanmod

Development

Build & Switch

sudo nixos-rebuild switch --flake .#bagalamukhi  # primary host
sudo nixos-rebuild switch --flake .#matangi      # Sara's host

Test

nixos-rebuild vm --flake .#bhairavi  # VM test
nixos-rebuild build --flake .#chhinamasta  # ISO build

Format

alejandra .  # format all .nix files

Flake Maintenance

nix flake update                    # update all inputs
nix flake lock --update-input stylix  # update one input
nix flake check                     # validate flake

Dev Shell

nix develop  # enter project dev shell

Conventions

  • Enable-by-option: Every module has options.modules.<cat>.<name>.enable guarded by mkIf
  • User modules: modules/nixos/users/ are never imported globally — each host imports only the users it needs
  • hardware-configuration.nix: Auto-generated by nixos-generate-config — do not edit manually
  • stateVersion: Set once per host/user, never change after first install
  • Overlays vs pkgs: Use pkgs/ for new packages, overlays/ for patches/overrides to existing ones
  • New Nix files: Must git add before building — Nix flake only sees tracked files
  • External configs: Managed as git submodules in external/, linked via mkOutOfStoreSymlink
  • Stylix: Sets theme for most apps automatically — avoid duplicating color/font config in individual modules
  • CRITICAL — Do NOT modify external/ directory: The external/ directory contains git submodules (awesome, nvim, firefox, base16_monokai_pro) that are managed in their own repos. Only modify files in external/ when explicitly instructed to do so. All NixOS configuration changes should be made in modules/, home/, hosts/, pkgs/, or overlays/.

Flake Inputs

Input Purpose
nixpkgs Primary package set (unstable)
stable Stable channel (nixos-25.05) for pinned packages
home-manager User environment management
stylix System-wide theming
nixos-hardware Hardware-specific modules
nur Nix User Repository
rust-overlay Latest Rust toolchain
nix-index-database Pre-built nix-index DB
bhairava-grub-theme Custom GRUB theme
nixos-generators VM/ISO/cloud image builder
nps Nix package search
sops-nix Secrets management (sops + age)
lightdm-webkit2-sanatana Sanatana glassmorphism sea-greeter theme (non-flake)

OpenCode Configuration

This project uses OpenCode with Hubs orchestration. Configuration lives in .opencode/:

Path Purpose Git
.opencode/opencode.jsonc Project-level OpenCode config ✓
.opencode/rules/ Project-specific rules (nix-flake-strategy, shell_strategy, context-strategy) ✓
.opencode/context/ Durable knowledge — frameworks, patterns, research, decisions ✓
.opencode/state/ Session state — checkpoints, todos, artifacts ✗ (gitignored)

Agent Routing

For this Nix/NixOS configuration project:

  • NixOS module changes → executor (default for .nix edits)
  • Architecture decisions → architect (flake structure, module refactoring)
  • Bug investigation → debugger (nixos-rebuild errors, eval trace)
  • Security review → security-reviewer (firewall, ssh, doas rules)
  • Code review → code-reviewer (module patterns, overlay correctness)
  • Testing → verifier (nixos-rebuild build, flake check)

Context Files

Project context is stored in .opencode/context/:

  • nix-nixos-home-manager-ecosystem.md — Full repo survey of Nix features
  • nix-nixos-home-manager-official-docs.md — Official docs reference (Context7)
  • decisions.md — Architecture Decision Records (ADRs)
  • frameworks/sea-greeter-display-manager.md — Sea greeter display manager integration
  • research/ — External research and references