nixpkgs/modules/home-manager/AGENTS.md

Home Manager Modules

User-level configuration modules organized by functional category.

Structure

home-manager/
├── default.nix      # Aggregator: imports all categories + ports.nix
├── ports.nix        # Port management (HM-specific: generateEnvVars)
├── cli/             # Terminal/CLI tools
│   ├── default.nix  # Category aggregator
│   └── zellij-ps.nix
└── coding/          # Development tools
    ├── default.nix  # Category aggregator
    └── editors.nix  # Neovim + Zed configs

Where to Look

Task	Location
Add CLI module	cli/<name>.nix, import in cli/default.nix
Add coding module	coding/<name>.nix, import in coding/default.nix
Add new category	Create <category>/default.nix, import in root default.nix
Module with host ports	Import ../../lib/ports.nix, use mkPortHelpers

Option Namespaces

• cli.* - CLI tools (e.g., cli.zellij-ps.enable)
• coding.editors.* - Editor configs (e.g., coding.editors.neovim.enable)
• m3ta.ports.* - Port management (shared with NixOS)

Patterns

Category aggregator (cli/default.nix):

{
  imports = [
    ./zellij-ps.nix
    # Add new modules here
  ];
}

Simple module (zellij-ps):

options.cli.zellij-ps = {
  enable = mkEnableOption "...";
  projectFolders = mkOption { type = types.listOf types.path; ... };
};
config = mkIf cfg.enable {
  home.packages = [ pkgs.zellij-ps ];
  home.sessionVariables.PROJECT_FOLDERS = ...;
};

Multi-config module (editors.nix):

config = mkMerge [
  (mkIf cfg.neovim.enable { programs.neovim = {...}; })
  (mkIf cfg.zed.enable { programs.zed-editor = {...}; })
  (mkIf (cfg.neovim.enable || cfg.zed.enable) { home.packages = [...]; })
];

HM vs NixOS Differences

Feature	Home Manager	NixOS
currentHost default	null (must set)	config.networking.hostName
generateEnvVars	Available	Not available
Output file	~/.config/m3ta/ports.json	/etc/m3ta/ports.json
Package access	pkgs.* via overlay	pkgs.* via overlay