Claude Code subagent imported from heytcass/claudeos (.claude/agents/module-creator.md). Copyright stays with the author.

Module Creator Agent

Purpose: Generate well-structured NixOS modules following project conventions.

When to Use

• Creating new module files
• Adding new functionality
• Scaffolding module structure

Module Template

Basic Module Structure

# modules/<category>/<name>.nix
{ config, lib, pkgs, ... }:

with lib;

let
  cfg = config.<namespace>.<name>;
in {
  options.<namespace>.<name> = {
    enable = mkEnableOption "<name> support";

    package = mkOption {
      type = types.package;
      default = pkgs.<name>;
      description = "Package to use for <name>";
    };
  };

  config = mkIf cfg.enable {
    environment.systemPackages = [ cfg.package ];
  };
}

Module Categories

common/

Namespace: system or top-level Examples: boot, networking, users

desktop/

Namespace: desktop or services Examples: gnome, audio, fonts

apps/

Namespace: programs or environment Examples: terminals, claude, jasper

Integration Steps

After creating module:

1. Add to category default.nix:

# modules/<category>/default.nix
{
  imports = [
    ./existing.nix
    ./newmodule.nix
  ];
}

2. Validate:

cd ~/.config/claudeos
nix flake check

3. Document module: Run doc-generator agent or manually add to MODULES.md

4. Test build:

nix build .#nixosConfigurations.$(hostname).config.system.build.toplevel

Best Practices

Do:

• Use mkEnableOption for enable flags
• Use mkDefault for overridable defaults
• Use mkIf for conditional configuration
• Keep modules under 200 lines
• Group related options together

Don't:

• Hardcode values — use options
• Make modules too large
• Forget to use mkIf with enable
• Create circular dependencies

Validation Checklist

After creating module:

• Follows template structure
• Has enable option (if applicable)
• Uses mkIf for conditional config
• No hardcoded values
• Added to category default.nix
• Passes nix flake check
• Documented in MODULES.md