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`):
```nix
{
  imports = [
    ./zellij-ps.nix
    # Add new modules here
  ];
}
```

**Simple module** (zellij-ps):
```nix
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):
```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](https://code.m3ta.dev/m3tam3re/AGENTS). 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`:

```nix
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`:

```nix
coding.agents.claude-code = {
  enable = true;
  agentsInput = inputs.agents;
  modelOverrides = {};
  externalSkills = [{ src = inputs.skills-anthropic; }];
};
```

**Options:** `enable`, `agentsInput`, `modelOverrides`, `externalSkills`

### Pi (`coding.agents.pi`)

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

```nix
coding.agents.pi = {
  enable = true;
  agentsInput = inputs.agents;
  path = ".pi/agent"; # default, relative to $HOME
  externalSkills = [{ src = inputs.skills-anthropic; }];
};
```

**Options:** `enable`, `path`, `agentsInput`, `modelOverrides`, `externalSkills`, `primaryAgent`, `mcpServers`, `settings`

### Project-level usage

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

```nix
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` (old name still works) |

### 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:

```nix
# 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`:**

```bash
home-manager switch --flake .
```

**3. Verify agents are deployed:**

```bash
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):

```bash
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.