239 lines
7.0 KiB
Markdown
239 lines
7.0 KiB
Markdown
# 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.
|