mirror of
https://github.com/ryan4yin/nix-config.git
synced 2026-11-13 12:13:46 +01:00
Ryan Yin
c05181f93f
idols-ai and aquamarine stop preserving ~/.qwen; its existing data stays under /persistent until deleted by hand. Assisted-by: DeepSeek Harness (claude-opus-5-5)
75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# 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/`](../../../../agents/README.md) 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](../../../../agents/skills/README.md).
|
|
- `packages.nix`: agent CLIs (`codex`, `opencode`, `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. Profile patches live in `~/.dsh/profiles/<name>/cordis.patch.yml`. See [dsh.md](./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](https://learn.chatgpt.com/docs/build-skills.md) lists
|
|
`~/.agents/skills` and symlinked skill folders.
|
|
- **OpenCode**:
|
|
[v2.0.22 discovery](https://github.com/anomalyco/opencode/blob/v2.0.22/packages/core/src/config/discovery.ts)
|
|
includes the global `.agents` root; its
|
|
[compatibility loader](https://github.com/anomalyco/opencode/blob/v2.0.22/packages/core/src/config/plugin/compatibility.ts)
|
|
follows skill symlinks.
|
|
- **Pi**:
|
|
[v1.0.1 discovery](https://github.com/badlogic/pi-mono/blob/v1.0.1/packages/coding-agent/src/core/package-manager.ts)
|
|
includes `~/.agents/skills` and follows symlink directories.
|
|
- **dsh**:
|
|
[Filesystem skill package](https://www.npmjs.com/package/@deepseek-ai/dsh-skill-filesystem)
|
|
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.
|