nixpkgs/AGENTS.md

m3ta-nixpkgs Knowledge Base

Generated: 2025-12-29 Commit: 9092e6d Branch: master

Overview

Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev shells. Flakes-only (no channels).

Structure

.
├── flake.nix              # Entry: packages, overlays, modules, shells, lib
├── pkgs/                  # Custom packages (one dir each, callPackage registry)
├── modules/
│   ├── nixos/             # System modules (ports.nix)
│   └── home-manager/      # User modules by category (cli/, coding/, ports.nix)
├── lib/                   # Shared utilities (ports.nix)
├── shells/                # Dev environments (default, python, devops)
├── overlays/mods/         # Package modifications (n8n version bump)
├── templates/             # Boilerplate for new packages/modules
└── examples/              # Usage examples

Where to Look

Task	Location	Notes
Add package	pkgs/<name>/default.nix	Register in pkgs/default.nix
Add NixOS module	modules/nixos/<name>.nix	Import in modules/nixos/default.nix
Add HM module	modules/home-manager/<category>/	Category: cli, coding, or root
Override nixpkgs pkg	overlays/mods/<name>.nix	Import in overlays/mods/default.nix
Add dev shell	shells/<name>.nix	Register in shells/default.nix
Use port management	config.m3ta.ports.get "service"	Host-specific via hostOverrides

Commands

nix flake check              # Validate flake
nix fmt                      # Format (nixpkgs-fmt)
nix build .#<pkg>            # Build package
nix flake show               # List outputs
nix develop                  # Enter dev shell
nix develop .#python         # Python shell
nix develop .#devops         # DevOps shell

# In dev shell only:
statix check .               # Lint
deadnix .                    # Find dead code

Code Style

Formatter: nix fmt before commit (nixpkgs-fmt)

Naming:

• Packages: lowercase-hyphen (e.g., hyprpaper-random)
• Variables: camelCase (e.g., portHelpers)
• Module options: m3ta.* namespace

Imports: Multi-line, trailing commas:

{
  lib,
  stdenv,
  fetchFromGitHub,
}:

Modules: Standard pattern:

{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
  };
  config = mkIf cfg.enable { ... };
}

Meta: Always include all fields:

meta = with lib; {
  description = "...";
  homepage = "...";
  license = licenses.mit;
  platforms = platforms.linux;
  mainProgram = "...";
};

Package Patterns

Rust (code2prompt):

rustPlatform.buildRustPackage rec {
  cargoLock.lockFile = src + "/Cargo.lock";
}

Shell scripts (launch-webapp):

writeShellScriptBin "name" ''script''
# Or mkDerivation with custom installPhase

AppImage (msty-studio):

appimageTools.wrapType2 { ... }

Custom fetcher (zellij-ps):

fetchFromGitea {
  domain = "code.m3ta.dev";
  owner = "m3tam3re";
  ...
}

Module Patterns

Simple enable (zellij-ps.nix):

options.cli.zellij-ps = {
  enable = mkEnableOption "...";
  someOption = mkOption { type = types.str; default = "..."; };
};
config = mkIf cfg.enable { home.packages = [...]; };

Multiple conditionals (editors.nix):

config = mkMerge [
  (mkIf cfg.neovim.enable { ... })
  (mkIf cfg.zed.enable { ... })
  (mkIf (cfg.neovim.enable || cfg.zed.enable) { ... })
];

Shared library (ports modules):

portsLib = import ../../lib/ports.nix { inherit lib; };
portHelpers = portsLib.mkPortHelpers { ports = cfg.definitions; ... };

Port Management

Central port management with host-specific overrides:

m3ta.ports = {
  enable = true;
  definitions = { nginx = 80; grafana = 3000; };
  hostOverrides.laptop = { nginx = 8080; };
  currentHost = config.networking.hostName;  # NixOS auto
};

# Usage
services.nginx.port = config.m3ta.ports.get "nginx";

Generated files: /etc/m3ta/ports.json (NixOS), ~/.config/m3ta/ports.json (HM)

Anti-Patterns

Don't	Do Instead
lib.fakeHash in commits	Get real hash: nix build, copy from error
Flat module files	Organize by category (cli/, coding/)
Hardcode ports	Use m3ta.ports module
Skip meta fields	Include all: description, homepage, license, platforms, mainProgram
with pkgs; in modules	Explicit pkgs.package or with pkgs; [ ... ] in lists only

Commit Format

type: brief description

Types: feat, fix, docs, style, refactor, chore

Gotchas

• Hash fetching: Use lib.fakeHash initially, build to get real hash
• HM modules: Category subdirs (cli/, coding/) have own default.nix aggregators
• Ports module: Different for NixOS vs HM (HM adds generateEnvVars option)
• Overlays: modifications overlay uses {prev}: pattern, not {final, prev}:
• Dev shell tools: statix, deadnix only available inside nix develop