nix-config-ryan4yin/home/base/tui/agents/README.md

Agents

Home Manager module that owns the Nix side of the AI coding agents: deploying the global rules and custom global skills, the agent CLIs, and their environment.

The canonical rules text, local skills, behavioral scenarios, and external-tool snippets live in the top-level agents/ directory. That directory stays portable Markdown with no Nix dependency; this module only wires it into place.

Files

• rules.nix: links the global rules to every agent's config location.
• skills.nix: links the global skills into ~/.agents/skills/<name>, from pinned flake inputs and from agents/skills/; the inventory is agents/skills/README.md.
• packages.nix: agent CLIs (codex, opencode2, pi) from the llm-agents flake input, dsh from nur-ryan4yin, pkgs.ctx7 for the find-docs skill, and pkgs.mcp-grafana for the Grafana MCP server. dsh's Nushell-only shell is selected when the package is built, via dsh.withPlugins with the plugin from the dsh-nu flake input, so it is a derivation choice rather than runtime state; profile patches live in ~/.dsh/profiles/<name>/cordis.patch.yml. See dsh.md for the layer order and the settings that bite.
• env.nix: telemetry and auto-update opt-outs for the agents.

Deployed rule targets

rules.nix creates one out-of-store symlink per target, all pointing at ~/nix-config/agents/global-rules.md:

Agent	Target
Codex	~/.codex/AGENTS.md
OpenCode	~/.config/opencode/AGENTS.md
Pi	~/.pi/agent/AGENTS.md
Cross-tool	~/.agents/AGENTS.md
dsh	~/.dsh/AGENTS.md

dsh reads both ~/.dsh/AGENTS.md ($DSH_HOME) and, from 0.2.1-alpha.2 on, ~/.agents/AGENTS.md ($DSH_AGENTS_HOME); identical content renders once.

Out-of-store means an edit to agents/global-rules.md takes effect on the next agent session without a Home Manager switch. The trade-off is that the rules stay writable in the checkout; use a store symlink (home.file.<target>.source = ../../../../agents/global-rules.md) if immutability matters more than fast iteration.

Global skills

skills.nix links every directory under agents/skills/ out-of-store, so an edit applies on the next session, and the skills selected from pinned flake inputs as store paths, which change only with a lock bump and a switch. Home Manager's normal collision checks apply: do not force replacement of an existing same-name skill, and do not install global skills with npx skills add -g alongside these links.

The installed releases support the shared root and symlinked skill directories, so no agent-specific compatibility links are needed:

• Codex: Skill documentation lists ~/.agents/skills and symlinked skill folders.
• OpenCode: v2.0.22 discovery includes the global .agents root; its compatibility loader follows skill symlinks.
• Pi: v1.0.1 discovery includes ~/.agents/skills and follows symlink directories.
• dsh: Filesystem skill package documents ~/.agents/skills and directory symlinks; confirmed in the shipped 0.2.1-rc.2 loader.

Adding or removing links requires a user-run Home Manager switch. Changes to an already-linked skill are available without a rebuild; start a new session or use the harness's reload mechanism to read them. After activation, verify the link target and that git-delivery appears in the skill catalog. Custom root overrides or disabled discovery still need runtime configuration.

The rules include a direct checkout fallback for git-delivery before its link is installed. Runtime permissions are not managed by this module.