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
    ├── opencode.nix # OpenCode non-agent config (theme, plugins, formatter)
    └── agents/      # Per-tool agent deployment (canonical TOML → rendered)
        ├── default.nix
        ├── opencode.nix    # File-based agents + skills + context
        ├── claude-code.nix # Claude Code agents + settings.json
        └── pi.nix          # Pi AGENTS.md + SYSTEM.md

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
Add agent renderer	coding/agents/<tool>.nix, import in coding/agents/default.nix

Option Namespaces

• cli.* - CLI tools (e.g., cli.zellij-ps.enable)
• coding.editors.* - Editor configs (e.g., coding.editors.neovim.enable)
• coding.opencode.* - OpenCode non-agent config (theme, plugins, formatter)
• coding.agents.opencode.* - OpenCode agent deployment (file-based agents)
• coding.agents.claude-code.* - Claude Code agent deployment
• coding.agents.pi.* - Pi agent deployment
• 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

Agent Modules

Agent definitions are stored as canonical agent.toml + system-prompt.md in the AGENTS repo. Renderers in lib/agents.nix transform these into tool-specific configs. Each tool has its own HM sub-module under coding/agents/.

OpenCode (coding.agents.opencode)

Renders file-based agents to ~/.config/opencode/agents/*.md:

coding.agents.opencode = {
  enable = true;
  agentsInput = inputs.agents;
  modelOverrides = {
    chiron = "anthropic/claude-sonnet-4";
  };
  externalSkills = [
    { src = inputs.skills-anthropic; }
  ];
};

Options: enable, agentsInput, modelOverrides, externalSkills

Claude Code (coding.agents.claude-code)

Renders agents to ~/.claude/agents/*.md + ~/.claude/settings.json:

coding.agents.claude-code = {
  enable = true;
  agentsInput = inputs.agents;
  modelOverrides = {};
};

Options: enable, agentsInput, modelOverrides

Pi (coding.agents.pi)

Renders AGENTS.md + SYSTEM.md to ~/.pi/agent/:

coding.agents.pi = {
  enable = true;
  agentsInput = inputs.agents;
};

Options: enable, agentsInput

Project-level usage

For per-project agent setup via flake.nix + direnv:

m3taLib.agents.shellHookForTool {
  inherit pkgs;
  agentsInput = inputs.agents;
  tool = "opencode";
  modelOverrides = { chiron = "anthropic/claude-sonnet-4"; };
};

Migration Guide (OpenCode agents)

The agent system was migrated from embedded agents.json to file-based canonical agent.toml definitions. Here is how to migrate your home-manager config.

What changed

Before	After
coding.opencode.agentsInput	coding.agents.opencode.agentsInput
coding.opencode.externalSkills	coding.agents.opencode.externalSkills
Agents embedded in config.json	File-based ~/.config/opencode/agents/*.md
Model hardcoded in agents.json	Per-machine modelOverrides
mkOpencodeRules	mkCodingRules

Migration steps

1. Update home-manager config:

Move agentsInput and externalSkills from coding.opencode to coding.agents.opencode. Add modelOverrides with the models previously hardcoded in agents.json:

# BEFORE (legacy):
coding.opencode = {
  enable = true;
  agentsInput = inputs.agents;
  externalSkills = [{ src = inputs.skills-anthropic; }];
  ohMyOpencodeSettings = { ... };
};

# AFTER (new):
coding.opencode = {
  enable = true;
  ohMyOpencodeSettings = { ... };
};

coding.agents.opencode = {
  enable = true;
  agentsInput = inputs.agents;
  externalSkills = [{ src = inputs.skills-anthropic; }];
  modelOverrides = {
    chiron = "zai-coding-plan/glm-5";
    "chiron-forge" = "zai-coding-plan/glm-5";
  };
};

2. Run home-manager switch:

home-manager switch --flake .

3. Verify agents are deployed:

ls ~/.config/opencode/agents/
# Should show: chiron.md chiron-forge.md hermes.md athena.md apollo.md calliope.md

4. Remove legacy files from AGENTS repo (after confirming everything works):

cd /home/m3tam3re/p/AI/AGENTS
rm agents/agents.json
rm prompts/chiron.txt prompts/chiron-forge.txt prompts/hermes.txt \
   prompts/athena.txt prompts/apollo.txt prompts/calliope.txt
rmdir prompts/  # if empty
# Also remove lib.agentsJson from flake.nix

5. Final cleanup: After legacy files are removed from AGENTS repo, remove lib.agentsJson from the AGENTS flake.nix (it's only needed for backward compatibility during the transition).

Key advantage of the new system

Prompt changes no longer require home-manager switch. Since agents are deployed as file-based ~/.config/opencode/agents/*.md (symlinks to Nix store), you only need to edit the system-prompt.md in the AGENTS repo, commit, update the flake lock, and run home-manager switch. Or for local development, edit the file directly and restart the tool.